System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 733f17fbf2a3177f6f7e9f0ef49640a46ab1bf9c:


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 35 22 0a 23 64 65 66 69 6e 65 20 53 51  .7.5".#define SQ
1030: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1040: 42 45 52 20 33 30 30 37 30 30 35 0a 23 64 65 66  BER 3007005.#def
1050: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1060: 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 31 2d  E_ID      "2011-
1070: 30 31 2d 32 38 20 31 37 3a 30 33 3a 35 30 20 65  01-28 17:03:50 e
1080: 64 37 35 39 64 35 61 39 65 64 62 33 62 62 61 35  d759d5a9edb3bba5
1090: 66 34 38 66 32 34 33 64 66 34 37 62 65 32 39 65  f48f243df47be29e
10a0: 33 66 65 38 63 64 37 22 0a 0a 2f 2a 0a 2a 2a 20  3fe8cd7"../*.** 
10b0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
10c0: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
10d0: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45  on Numbers.** KE
10e0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
10f0: 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33  version, sqlite3
1100: 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20  _sourceid.**.** 
1110: 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  These interfaces
1120: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d   provide the sam
1130: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  e information as
1140: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52   the [SQLITE_VER
1150: 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  SION],.** [SQLIT
1160: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1170: 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53  ], and [SQLITE_S
1180: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
1190: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a  rocessor macros.
11a0: 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63  ** but are assoc
11b0: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c  iated with the l
11c0: 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f  ibrary instead o
11d0: 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  f the header fil
11e0: 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a  e.  ^(Cautious.*
11f0: 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  * programmers mi
1200: 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65  ght include asse
1210: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20  rt() statements 
1220: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
1230: 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66  tion to.** verif
1240: 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65  y that values re
1250: 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1260: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68  interfaces match
1270: 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a   the macros in.*
1280: 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e  * the header, an
1290: 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68  d thus insure th
12a0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
12b0: 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  on is.** compile
12c0: 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20  d with matching 
12d0: 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64  library and head
12e0: 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  er files..**.** 
12f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1300: 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c  >.** assert( sql
1310: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1320: 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45  number()==SQLITE
1330: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
1340: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1350: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75  rcmp(sqlite3_sou
1360: 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53  rceid(),SQLITE_S
1370: 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a  OURCE_ID)==0 );.
1380: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
1390: 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  p(sqlite3_libver
13a0: 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45  sion(),SQLITE_VE
13b0: 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20  RSION)==0 );.** 
13c0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13d0: 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
13e0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
13f0: 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  [] string consta
1400: 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  nt contains the 
1410: 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f  text of [SQLITE_
1420: 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72  VERSION].** macr
1430: 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  o.  ^The sqlite3
1440: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75  _libversion() fu
1450: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1460: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
1470: 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  ** to the sqlite
1480: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
1490: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
14a0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
14b0: 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69  sion().** functi
14c0: 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  on is provided f
14d0: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73  or use in DLLs s
14e0: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75  ince DLL users u
14f0: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61  sually do not ha
1500: 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63  ve.** direct acc
1510: 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f  ess to string co
1520: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74  nstants within t
1530: 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a  he DLL.  ^The.**
1540: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1550: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e  ion_number() fun
1560: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e  ction returns an
1570: 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74   integer equal t
1580: 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  o.** [SQLITE_VER
1590: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e  SION_NUMBER].  ^
15a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  The sqlite3_sour
15b0: 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  ceid() function 
15c0: 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f  returns .** a po
15d0: 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e  inter to a strin
15e0: 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65  g constant whose
15f0: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61   value is the sa
1600: 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53  me as the .** [S
1610: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d  QLITE_SOURCE_ID]
1620: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1630: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  macro..**.** See
1640: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76   also: [sqlite_v
1650: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1660: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1670: 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1680: 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  I SQLITE_EXTERN 
1690: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
16a0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51  e3_version[];.SQ
16b0: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
16c0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
16d0: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53  version(void);.S
16e0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16f0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1700: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51  urceid(void);.SQ
1710: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1720: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1730: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1740: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1750: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1760: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69  Compilation Opti
1770: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a  ons Diagnostics.
1780: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1790: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
17a0: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e  _used() function
17b0: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20   returns 0 or 1 
17c0: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77  .** indicating w
17d0: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69  hether the speci
17e0: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20  fied option was 
17f0: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63  defined at .** c
1800: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54  ompile time.  ^T
1810: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69  he SQLITE_ prefi
1820: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  x may be omitted
1830: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70   from the .** op
1840: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64  tion name passed
1850: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
1860: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1870: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .  .**.** ^The s
1880: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1890: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74  tion_get() funct
18a0: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61  ion allows itera
18b0: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65  ting.** over the
18c0: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73   list of options
18d0: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e   that were defin
18e0: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  ed at compile ti
18f0: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69  me by.** returni
1900: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70  ng the N-th comp
1910: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile time option 
1920: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69  string.  ^If N i
1930: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a  s out of range,.
1940: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
1950: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72  leoption_get() r
1960: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1970: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c  inter.  ^The SQL
1980: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20  ITE_ .** prefix 
1990: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
19a0: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75  any strings retu
19b0: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  rned by .** sqli
19c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19d0: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  n_get()..**.** ^
19e0: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20  Support for the 
19f0: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74  diagnostic funct
1a00: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ions sqlite3_com
1a10: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a20: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ).** and sqlite3
1a30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a40: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74  et() may be omit
1a50: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e  ted by specifyin
1a60: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  g the .** [SQLIT
1a70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1a80: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69  TION_DIAGS] opti
1a90: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  on at compile ti
1aa0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  me..**.** See al
1ab0: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  so: SQL function
1ac0: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  s [sqlite_compil
1ad0: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20  eoption_used()] 
1ae0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63  and.** [sqlite_c
1af0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b00: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d  ()] and the [com
1b10: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61  pile_options pra
1b20: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  gma]..*/.#ifndef
1b30: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
1b40: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
1b50: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1b60: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1b70: 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74  ption_used(const
1b80: 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29   char *zOptName)
1b90: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
1ba0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1bb0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1bc0: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
1bd0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1be0: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
1bf0: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
1c00: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
1c10: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1c20: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
1c30: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
1c40: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
1c50: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
1c60: 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69 6e 67  ompiled mutexing
1c70: 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20 64 75   code omitted du
1c80: 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  e to the.** [SQL
1c90: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1ca0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
1cb0: 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20 74 6f  ion being set to
1cc0: 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65   0..**.** SQLite
1cd0: 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64   can be compiled
1ce0: 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f 75 74   with or without
1cf0: 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65 6e 0a   mutexes.  When.
1d00: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
1d10: 48 52 45 41 44 53 41 46 45 5d 20 43 20 70 72 65  HREADSAFE] C pre
1d20: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
1d30: 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74 65 78  is 1 or 2, mutex
1d40: 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
1d50: 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69 73 20  d and SQLite is 
1d60: 74 68 72 65 61 64 73 61 66 65 2e 20 20 57 68 65  threadsafe.  Whe
1d70: 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  n the.** [SQLITE
1d80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63  _THREADSAFE] mac
1d90: 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65  ro is 0, .** the
1da0: 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f 6d 69   mutexes are omi
1db0: 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74 20 74  tted.  Without t
1dc0: 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74 20 69  he mutexes, it i
1dd0: 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f  s not safe.** to
1de0: 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f 6e 63   use SQLite conc
1df0: 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f  urrently from mo
1e00: 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68 72 65  re than one thre
1e10: 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69  ad..**.** Enabli
1e20: 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63 75 72  ng mutexes incur
1e30: 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65 20 70  s a measurable p
1e40: 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c  erformance penal
1e50: 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65  ty..** So if spe
1e60: 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73 74 20  ed is of utmost 
1e70: 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d  importance, it m
1e80: 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20 64 69  akes sense to di
1e90: 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74  sable.** the mut
1ea0: 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72 20 6d  exes.  But for m
1eb0: 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d  aximum safety, m
1ec0: 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20 62 65  utexes should be
1ed0: 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68   enabled..** ^Th
1ee0: 65 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69  e default behavi
1ef0: 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65 78 65  or is for mutexe
1f00: 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e  s to be enabled.
1f10: 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
1f20: 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
1f30: 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63 61 74  d by an applicat
1f40: 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ion to make sure
1f50: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76 65 72   that the.** ver
1f60: 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65 20 74  sion of SQLite t
1f70: 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e  hat it is linkin
1f80: 67 20 61 67 61 69 6e 73 74 20 77 61 73 20 63 6f  g against was co
1f90: 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
1fa0: 68 65 20 64 65 73 69 72 65 64 20 73 65 74 74 69  he desired setti
1fb0: 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  ng of the [SQLIT
1fc0: 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d 61  E_THREADSAFE] ma
1fd0: 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  cro..**.** This 
1fe0: 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79 20 72  interface only r
1ff0: 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20 63 6f  eports on the co
2000: 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78  mpile-time mutex
2010: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74   setting.** of t
2020: 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
2030: 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20 49 66  DSAFE] flag.  If
2040: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
2050: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49  led with.** SQLI
2060: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 20  TE_THREADSAFE=1 
2070: 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74 65 78  or =2 then mutex
2080: 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  es are enabled b
2090: 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a  y default but.**
20a0: 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72   can be fully or
20b0: 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73 61 62   partially disab
20c0: 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61 6c 6c  led using a call
20d0: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
20e0: 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74  fig()].** with t
20f0: 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49 54 45  he verbs [SQLITE
2100: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
2110: 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43  READ], [SQLITE_C
2120: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
2130: 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  D],.** or [SQLIT
2140: 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e  E_CONFIG_MUTEX].
2150: 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e 20 76    ^(The return v
2160: 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73  alue of the.** s
2170: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2180: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  e() function sho
2190: 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70  ws only the comp
21a0: 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69 6e 67  ile-time setting
21b0: 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20 73 61   of.** thread sa
21c0: 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75  fety, not any ru
21d0: 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73 20 74  n-time changes t
21e0: 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 6d  o that setting m
21f0: 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65  ade by.** sqlite
2200: 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f  3_config(). In o
2210: 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
2220: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
2230: 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  m sqlite3_thread
2240: 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63  safe().** is unc
2250: 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c 73 20  hanged by calls 
2260: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  to sqlite3_confi
2270: 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  g().)^.**.** See
2280: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
2290: 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74  mode] documentat
22a0: 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ion for addition
22b0: 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
22c0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
22d0: 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  t sqlite3_thread
22e0: 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  safe(void);../*.
22f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
2300: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2310: 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59 57 4f   Handle.** KEYWO
2320: 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65 20 63  RDS: {database c
2330: 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61 74 61  onnection} {data
2340: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
2350: 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f 70 65  }.**.** Each ope
2360: 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
2370: 65 20 69 73 20 72 65 70 72 65 73 65 6e 74 65 64  e is represented
2380: 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   by a pointer to
2390: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 0a   an instance of.
23a0: 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20 73 74  ** the opaque st
23b0: 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20 22 73  ructure named "s
23c0: 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69 73 20  qlite3".  It is 
23d0: 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e 6b 20  useful to think 
23e0: 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a 2a 2a  of an sqlite3.**
23f0: 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e 20 6f   pointer as an o
2400: 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73 71 6c  bject.  The [sql
2410: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
2420: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
2430: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2440: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74  3_open_v2()] int
2450: 65 72 66 61 63 65 73 20 61 72 65 20 69 74 73 20  erfaces are its 
2460: 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20 61 6e  constructors, an
2470: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2480: 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20 64 65  ()].** is its de
2490: 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65 72 65  structor.  There
24a0: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 20   are many other 
24b0: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
24c0: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
24d0: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
24e0: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
24f0: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
2500: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
2510: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
2520: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
2530: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
2540: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
2550: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
2560: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2570: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
2580: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
2590: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
25a0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
25b0: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
25c0: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
25d0: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
25e0: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
25f0: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
2600: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
2610: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
2620: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
2630: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
2640: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
2650: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
2660: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
2670: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
2680: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
2690: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
26a0: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
26b0: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
26c0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
26d0: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
26e0: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
26f0: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
2700: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
2710: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
2720: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
2730: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
2740: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2750: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
2760: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
2770: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
2780: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
2790: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
27a0: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
27b0: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
27c0: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
27d0: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
27e0: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
27f0: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
2800: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
2810: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
2820: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
2830: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
2840: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
2850: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
2860: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49  ef unsigned SQLI
2870: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f  if defined(_MSC_
28a0: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28  VER) || defined(
28b0: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20  __BORLANDC__).  
28c0: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20  typedef __int64 
28d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
28e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
28f0: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
2900: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20  uint64;.#else.  
2910: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e  typedef long lon
2920: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74  g int sqlite_int
2930: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2940: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67  signed long long
2950: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74   int sqlite_uint
2960: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64  64;.#endif.typed
2970: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  ef sqlite_int64 
2980: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74  sqlite3_int64;.t
2990: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69  ypedef sqlite_ui
29a0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e  nt64 sqlite3_uin
29b0: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63  t64;../*.** If c
29c0: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70  ompiling for a p
29d0: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61  rocessor that la
29e0: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  cks floating poi
29f0: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73  nt support,.** s
2a00: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65  ubstitute intege
2a10: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70  r for floating-p
2a20: 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  oint..*/.#ifdef 
2a30: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
2a40: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66  TING_POINT.# def
2a50: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  ine double sqlit
2a60: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a  e3_int64.#endif.
2a70: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a80: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62   Closing A Datab
2a90: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
2aa0: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2ab0: 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74 69 6e  3_close() routin
2ac0: 65 20 69 73 20 74 68 65 20 64 65 73 74 72 75 63  e is the destruc
2ad0: 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  tor for the [sql
2ae0: 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  ite3] object..**
2af0: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
2b00: 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74 75 72  e3_close() retur
2b10: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 74  n SQLITE_OK if t
2b20: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2b30: 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63 65 73  ect is.** succes
2b40: 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64  sfully destroyed
2b50: 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61   and all associa
2b60: 74 65 64 20 72 65 73 6f 75 72 63 65 73 20 61 72  ted resources ar
2b70: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e 0a 2a  e deallocated..*
2b80: 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
2b90: 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65 33 5f  s must [sqlite3_
2ba0: 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
2bb0: 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72  ize] all [prepar
2bc0: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 0a 2a  ed statements].*
2bd0: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  * and [sqlite3_b
2be0: 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73  lob_close | clos
2bf0: 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e  e] all [BLOB han
2c00: 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74 65 64  dles] associated
2c10: 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 73 71   with.** the [sq
2c20: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2c30: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2c40: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2c50: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2c60: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69  qlite3_close() i
2c70: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
2c80: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c90: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
2ca0: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
2cb0: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
2cc0: 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c 4f 42  ements] or [BLOB
2cd0: 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65 6e 20   handles], then 
2ce0: 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  it returns.** SQ
2cf0: 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a 2a 2a  LITE_BUSY..**.**
2d00: 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f 63 6c   ^If [sqlite3_cl
2d10: 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f 6b 65  ose()] is invoke
2d20: 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61  d while a transa
2d30: 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a  ction is open,.*
2d40: 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  * the transactio
2d50: 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  n is automatical
2d60: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
2d70: 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61  **.** The C para
2d80: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2d90: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75 73 74  3_close(C)] must
2da0: 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55 4c   be either a NUL
2db0: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20  L.** pointer or 
2dc0: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
2dd0: 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74 61  ect pointer obta
2de0: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  ined.** from [sq
2df0: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
2e00: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
2e10: 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
2e20: 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e  3_open_v2()], an
2e30: 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c 79  d not previously
2e40: 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c   closed..** ^Cal
2e50: 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f  ling sqlite3_clo
2e60: 73 65 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c  se() with a NULL
2e70: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
2e80: 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72 6d 6c  t is a .** harml
2e90: 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 53 51  ess no-op..*/.SQ
2ea0: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2eb0: 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74  ite3_close(sqlit
2ec0: 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  e3 *);../*.** Th
2ed0: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
2ee0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
2ef0: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
2f00: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
2f10: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
2f20: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
2f30: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
2f40: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
2f50: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
2f60: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
2f70: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
2f80: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
2f90: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
2fa0: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
2fb0: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
2fc0: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a   Interface.**.**
2fd0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
2fe0: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
2ff0: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3000: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3010: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3020: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3030: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
3040: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
3050: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
3060: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
3070: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
3080: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
3090: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
30a0: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
30b0: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
30c0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
30d0: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
30e0: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
30f0: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3100: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3110: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3120: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3130: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
3140: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
3150: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
3160: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
3170: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
3180: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
3190: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
31a0: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
31b0: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
31c0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
31d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
31e0: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
31f0: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3200: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3210: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3220: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3230: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
3240: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
3250: 6e 74 20 74 6f 0a 2a 2a 20 74 6f 20 73 71 6c 69  nt to.** to sqli
3260: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65  te3_exec() is re
3270: 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f  layed through to
3280: 20 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e   the 1st argumen
3290: 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c  t of each.** cal
32a0: 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e  lback invocation
32b0: 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62  .  ^If the callb
32c0: 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ack pointer to s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
32e0: 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e   is NULL, then n
32f0: 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76  o callback is ev
3300: 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72  er invoked and r
3310: 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a  esult rows are.*
3320: 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  * ignored..**.**
3330: 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63   ^If an error oc
3340: 63 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75  curs while evalu
3350: 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74  ating the SQL st
3360: 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20  atements passed 
3370: 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  into.** sqlite3_
3380: 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65  exec(), then exe
3390: 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75  cution of the cu
33a0: 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20  rrent statement 
33b0: 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62  stops and.** sub
33c0: 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e  sequent statemen
33d0: 74 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20  ts are skipped. 
33e0: 20 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72   ^If the 5th par
33f0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3400: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e  3_exec().** is n
3410: 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79  ot NULL then any
3420: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69   error message i
3430: 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d  s written into m
3440: 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a  emory obtained.*
3450: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3460: 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61  malloc()] and pa
3470: 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67  ssed back throug
3480: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3490: 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64  ter..** To avoid
34a0: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74   memory leaks, t
34b0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
34c0: 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71  hould invoke [sq
34d0: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a  lite3_free()].**
34e0: 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   on error messag
34f0: 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e  e strings return
3500: 65 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ed through the 5
3510: 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a  th parameter of.
3520: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78  ** of sqlite3_ex
3530: 65 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65  ec() after the e
3540: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
3550: 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  ing is no longer
3560: 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20   needed..** ^If 
3570: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
3580: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3590: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  c() is not NULL 
35a0: 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a  and no errors.**
35b0: 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c   occur, then sql
35c0: 69 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73  ite3_exec() sets
35d0: 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   the pointer in 
35e0: 69 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65  its 5th paramete
35f0: 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66  r to.** NULL bef
3600: 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
3610: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69  *.** ^If an sqli
3620: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3630: 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
3640: 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65  zero, the sqlite
3650: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74  3_exec().** rout
3660: 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49  ine returns SQLI
3670: 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74  TE_ABORT without
3680: 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61   invoking the ca
3690: 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64  llback again and
36a0: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e  .** without runn
36b0: 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65  ing any subseque
36c0: 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  nt SQL statement
36d0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e  s..**.** ^The 2n
36e0: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
36f0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3700: 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
3710: 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  on is the.** num
3720: 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
3730: 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e  n the result.  ^
3740: 54 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74  The 3rd argument
3750: 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
3760: 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61  exec().** callba
3770: 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ck is an array o
3780: 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  f pointers to st
3790: 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61  rings obtained a
37a0: 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  s if from.** [sq
37b0: 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
37c0: 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61  t()], one for ea
37d0: 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20  ch column.  ^If 
37e0: 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a  an element of a.
37f0: 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73  ** result row is
3800: 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63   NULL then the c
3810: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72  orresponding str
3820: 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20  ing pointer for 
3830: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  the.** sqlite3_e
3840: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  xec() callback i
3850: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
3860: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
3870: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73  ment to the.** s
3880: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3890: 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72  llback is an arr
38a0: 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74  ay of pointers t
38b0: 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20  o strings where 
38c0: 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65  each.** entry re
38d0: 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d  presents the nam
38e0: 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69  e of correspondi
38f0: 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  ng result column
3900: 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20   as obtained.** 
3910: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f  from [sqlite3_co
3920: 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a  lumn_name()]..**
3930: 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20  .** ^If the 2nd 
3940: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
3950: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61  ite3_exec() is a
3960: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61   NULL pointer, a
3970: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61   pointer.** to a
3980: 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
3990: 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61  or a pointer tha
39a0: 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20  t contains only 
39b0: 77 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f  whitespace and/o
39c0: 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e  r .** SQL commen
39d0: 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20  ts, then no SQL 
39e0: 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65  statements are e
39f0: 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65  valuated and the
3a00: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20   database.** is 
3a10: 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a  not changed..**.
3a20: 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a  ** Restrictions:
3a30: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
3a40: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
3a50: 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20  ion must insure 
3a60: 74 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72  that the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20  3_exec().**     
3a90: 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20   is a valid and 
3aa0: 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63  open [database c
3ab0: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c  onnection]..** <
3ac0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
3ad0: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f  ion must not clo
3ae0: 73 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  se [database con
3af0: 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
3b00: 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68  ed by.**      th
3b10: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
3b20: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3b30: 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  ) while sqlite3_
3b40: 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e  exec() is runnin
3b50: 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  g..** <li> The a
3b60: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3b70: 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53  not modify the S
3b80: 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
3b90: 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  t passed into.**
3ba0: 20 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61        the 2nd pa
3bb0: 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
3bc0: 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20  e3_exec() while 
3bd0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3be0: 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f  s running..** </
3bf0: 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul>.*/.SQLITE_AP
3c00: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  I int sqlite3_ex
3c10: 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ec(.  sqlite3*, 
3c20: 20 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 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
3c50: 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
3c60: 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20  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 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
3c90: 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
3ca0: 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29   int (*callback)
3cb0: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3cc0: 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43  *,char**),  /* C
3cd0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
3ce0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20   */.  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 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74   /* 1st argument
3d20: 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a   to callback */.
3d30: 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20    char **errmsg 
3d40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d50: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
3d60: 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
3d70: 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  n here */.);../*
3d80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
3d90: 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45  sult Codes.** KE
3da0: 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f  YWORDS: SQLITE_O
3db0: 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b  K {error code} {
3dc0: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
3dd0: 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c  KEYWORDS: {resul
3de0: 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20  t code} {result 
3df0: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e  codes}.**.** Man
3e00: 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f  y SQLite functio
3e10: 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74  ns return an int
3e20: 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65  eger result code
3e30: 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68   from the set sh
3e40: 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f  own.** here in o
3e50: 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65  rder to indicate
3e60: 73 20 73 75 63 63 65 73 73 20 6f 72 20 66 61 69  s success or fai
3e70: 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  lure..**.** New 
3e80: 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20  error codes may 
3e90: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
3ea0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
3eb0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  QLite..**.** See
3ec0: 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49   also: [SQLITE_I
3ed0: 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65  OERR_READ | exte
3ee0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
3ef0: 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s].*/.#define SQ
3f00: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3f10: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3f20: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3f30: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
3f40: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
3f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
3f60: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
3f70: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
3f80: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
3f90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3fa0: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
3fb0: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
3fc0: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
3fd0: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
3fe0: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
3ff0: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
4000: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
4010: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4020: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
4030: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
4040: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
4050: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
4060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
4070: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
4080: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
4090: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
40a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40b0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
40c0: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
40d0: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
40e0: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
40f0: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
4100: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
4110: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
4120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4130: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
4140: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
4150: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
4160: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
4170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
4180: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
4190: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
41a0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
41b0: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
41c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
41d0: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
41e0: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
41f0: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
4200: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
4210: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
4220: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
4230: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
4240: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
4250: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4260: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
4270: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
4280: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
4290: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
42a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
42b0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
42c0: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
42d0: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
42e0: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
42f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4300: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
4310: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
4320: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
4330: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
4340: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
4350: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
4360: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
4370: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
4380: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
4390: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
43a0: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
43b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
43c0: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
43d0: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
43e0: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
43f0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4400: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
4410: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
4420: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
4430: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
4440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
4450: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
4460: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
4470: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
4480: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
4490: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
44a0: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
44b0: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
44c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
44d0: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
44e0: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
44f0: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
4500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
4510: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
4520: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
4530: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
4540: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
4550: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
4560: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
4570: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
4580: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4590: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
45a0: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
45b0: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
45c0: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
45d0: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
45e0: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
45f0: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4600: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
4610: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
4620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
4630: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
4640: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
4650: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
4660: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4670: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
4680: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
4690: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
46a0: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
46b0: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
46c0: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
46d0: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
46e0: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
46f0: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4700: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
4710: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
4720: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
4730: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
4740: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
4750: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
4760: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
4770: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4780: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4790: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
47a0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
47b0: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
47c0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
47d0: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
47e0: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
47f0: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4800: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
4810: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
4820: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
4830: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
4840: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
4850: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
4860: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4870: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4880: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4890: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
48a0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
48b0: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
48c0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
48d0: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
48e0: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
48f0: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4900: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4910: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
4920: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
4930: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
4940: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
4950: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
4960: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4970: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4980: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4990: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
49a0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
49b0: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
49c0: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
49d0: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
49e0: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
49f0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4a00: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
4a10: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
4a20: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
4a30: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
4a40: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4a50: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
4a60: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
4a70: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
4a80: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
4a90: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
4aa0: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
4ab0: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
4ac0: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
4ad0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4ae0: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
4af0: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
4b00: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
4b10: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
4b20: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
4b30: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
4b40: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
4b50: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
4b60: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
4b70: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
4b80: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
4b90: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
4ba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4bb0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
4bc0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4bd0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4be0: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4bf0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
4c00: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4c10: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
4c20: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4c30: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4c40: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4c50: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4c60: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4c70: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
4c80: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c90: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
4ca0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4cb0: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
4cc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4cd0: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4ce0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4cf0: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
4d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4d10: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
4d20: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4d30: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4d40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4d50: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
4d60: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d70: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
4d80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d90: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
4da0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4db0: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
4dc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4dd0: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
4de0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4df0: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
4e00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e10: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
4e20: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e30: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4e40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e50: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4e60: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e70: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
4e80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e90: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
4ea0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4eb0: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
4ec0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ed0: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
4ee0: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
4ef0: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
4f00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f10: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
4f20: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f30: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
4f40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f50: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4f60: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f70: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
4f80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f90: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
4fa0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fb0: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4fc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fd0: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
4fe0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ff0: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
5000: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5010: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
5020: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5030: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
5040: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5050: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
5060: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5070: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
5080: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5090: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
50a0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
50b0: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
50c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
50d0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
50e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
50f0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5100: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5110: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5120: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5130: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5140: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
5150: 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65  : Flags For File
5160: 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73   Open Operations
5170: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74  .**.** These bit
5180: 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65   values are inte
5190: 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
51a0: 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d  the.** 3rd param
51b0: 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  eter to the [sql
51c0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
51d0: 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a  interface and.**
51e0: 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72 61   in the 4th para
51f0: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78 4f 70  meter to the xOp
5200: 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  en method of the
5210: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
5220: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65  ] object..*/.#de
5230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5240: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
5250: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
5260: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5270: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5280: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5290: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
52a0: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
52b0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
52c0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
52d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
52e0: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
52f0: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
5300: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5310: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5320: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5330: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
5340: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
5350: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5360: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5370: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
5380: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
5390: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
53a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53b0: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
53c0: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
53d0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
53e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
53f0: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
5400: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
5410: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5420: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5430: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
5440: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
5450: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5460: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5470: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
5480: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
5490: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
54a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
54b0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
54c0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
54d0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
54e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
54f0: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
5500: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
5510: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5520: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5530: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
5540: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
5550: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
5560: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5570: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
5580: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
5590: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
55a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
55b0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
55c0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
55d0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
55e0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
55f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5600: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
5610: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
5620: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5630: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5640: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
5650: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5660: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
5670: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
5680: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
5690: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
56a0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
56b0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
56c0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
56d0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
56e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
56f0: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
5700: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
5710: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
5720: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
5730: 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69 73  vice Characteris
5740: 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  tics.**.** The x
5750: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
5760: 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66 20  stics method of 
5770: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
5780: 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65  methods].** obje
5790: 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  ct returns an in
57a0: 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 61  teger which is a
57b0: 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 20 74   vector of the t
57c0: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
57d0: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
57e0: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
57f0: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
5800: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
5810: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
5820: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
5830: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5840: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
5850: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
5860: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
5870: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
5880: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
5890: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
58a0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
58b0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
58c0: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
58d0: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
58e0: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
58f0: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
5900: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
5910: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
5920: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
5930: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
5940: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
5950: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
5960: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
5970: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
5980: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
5990: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
59a0: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
59b0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
59c0: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
59d0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
59e0: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
59f0: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
5a00: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
5a10: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
5a20: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
5a30: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
5a40: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
5a50: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
5a60: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
5a70: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
5a80: 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2f 0a  to xWrite()..*/.
5a90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5aa0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
5ab0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5ac0: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
5ad0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5ae0: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
5af0: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
5b00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5b10: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
5b20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5b30: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
5b40: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
5b50: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
5b60: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
5b70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5b80: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
5b90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ba0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
5bb0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
5bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
5bd0: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
5be0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5bf0: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
5c00: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
5c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5c20: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
5c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
5c40: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
5c50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5c60: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
5c70: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
5c80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5c90: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
5ca0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5cb0: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
5cc0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
5cd0: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
5ce0: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
5cf0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5d00: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
5d10: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
5d20: 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  800../*.** CAPI3
5d30: 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e  REF: File Lockin
5d40: 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53  g Levels.**.** S
5d50: 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f  QLite uses one o
5d60: 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  f these integer 
5d70: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
5d80: 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  cond.** argument
5d90: 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b   to calls it mak
5da0: 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28  es to the xLock(
5db0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
5dc0: 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e  methods.** of an
5dd0: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
5de0: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  hods] object..*/
5df0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e00: 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20  LOCK_NONE       
5e10: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
5e20: 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20  ITE_LOCK_SHARED 
5e30: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
5e40: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53   SQLITE_LOCK_RES
5e50: 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65  ERVED      2.#de
5e60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5e70: 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33  _PENDING       3
5e80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5e90: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20  LOCK_EXCLUSIVE  
5ea0: 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     4../*.** CAPI
5eb0: 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a  3REF: Synchroniz
5ec0: 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73  ation Type Flags
5ed0: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69  .**.** When SQLi
5ee0: 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78  te invokes the x
5ef0: 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66  Sync() method of
5f00: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
5f10: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5f20: 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d  ct it uses a com
5f30: 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74  bination of.** t
5f40: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
5f50: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
5f60: 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
5f70: 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54  * When the SQLIT
5f80: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
5f90: 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74  flag is used, it
5fa0: 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a   means that the.
5fb0: 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  ** sync operatio
5fc0: 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  n only needs to 
5fd0: 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61  flush data to ma
5fe0: 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f  ss storage.  Ino
5ff0: 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  de.** informatio
6000: 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c  n need not be fl
6010: 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f  ushed. If the lo
6020: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66  wer four bits of
6030: 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75   the flag.** equ
6040: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  al SQLITE_SYNC_N
6050: 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e  ORMAL, that mean
6060: 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20  s to use normal 
6070: 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63  fsync() semantic
6080: 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77  s..** If the low
6090: 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75  er four bits equ
60a0: 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  al SQLITE_SYNC_F
60b0: 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ULL, that means.
60c0: 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53  ** to use Mac OS
60d0: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
60e0: 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79  c instead of fsy
60f0: 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e  nc()..**.** Do n
6100: 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53  ot confuse the S
6110: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6120: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
6130: 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20  C_FULL flags.** 
6140: 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41  with the [PRAGMA
6150: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f   synchronous]=NO
6160: 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41  RMAL and [PRAGMA
6170: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55   synchronous]=FU
6180: 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20  LL.** settings. 
6190: 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75   The [synchronou
61a0: 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d  s pragma] determ
61b0: 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20  ines when calls 
61c0: 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20  to the.** xSync 
61d0: 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72  VFS method occur
61e0: 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69   and applies uni
61f0: 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c  formly across al
6200: 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20  l platforms..** 
6210: 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  The SQLITE_SYNC_
6220: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
6230: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
6240: 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a  s determine how.
6250: 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20  ** energetic or 
6260: 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63  rigorous or forc
6270: 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70  eful the sync op
6280: 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64  erations are and
6290: 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20  .** only make a 
62a0: 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61  difference on Ma
62b0: 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65  c OSX for the de
62c0: 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64  fault SQLite cod
62d0: 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72  e..** (Third-par
62e0: 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ty VFS implement
62f0: 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73  ations might als
6300: 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  o make the disti
6310: 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65  nction.** betwee
6320: 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  n SQLITE_SYNC_NO
6330: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6340: 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61  SYNC_FULL, but a
6350: 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72  mong the.** oper
6360: 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61  ating systems na
6370: 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64  tively supported
6380: 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79   by SQLite, only
6390: 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65   Mac OSX.** care
63a0: 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66  s about the diff
63b0: 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66  erence.).*/.#def
63c0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
63d0: 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78  NORMAL        0x
63e0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
63f0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20  LITE_SYNC_FULL  
6400: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a          0x00003.
6410: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
6420: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20  YNC_DATAONLY    
6430: 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a    0x00010../*.**
6440: 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e   CAPI3REF: OS In
6450: 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c  terface Open Fil
6460: 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41  e Handle.**.** A
6470: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
6480: 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
6490: 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ts an open file 
64a0: 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  in the .** [sqli
64b0: 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74  te3_vfs | OS int
64c0: 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20  erface layer].  
64d0: 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e  Individual OS in
64e0: 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65  terface.** imple
64f0: 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a  mentations will.
6500: 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c  ** want to subcl
6510: 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20  ass this object 
6520: 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64  by appending add
6530: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a  itional fields.*
6540: 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20  * for their own 
6550: 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f  use.  The pMetho
6560: 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f  ds entry is a po
6570: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
6580: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6590: 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20  ds] object that 
65a0: 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20  defines methods 
65b0: 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a  for performing.*
65c0: 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  * I/O operations
65d0: 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c   on the open fil
65e0: 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  e..*/.typedef st
65f0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c  ruct sqlite3_fil
6600: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a  e sqlite3_file;.
6610: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66  struct sqlite3_f
6620: 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74  ile {.  const st
6630: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
6640: 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64  methods *pMethod
6650: 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66  s;  /* Methods f
6660: 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  or an open file 
6670: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
6680: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
6690: 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c  ace File Virtual
66a0: 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a   Methods Object.
66b0: 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65  **.** Every file
66c0: 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b   opened by the [
66d0: 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 4f 70  sqlite3_vfs] xOp
66e0: 65 6e 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61  en method popula
66f0: 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74  tes an.** [sqlit
6700: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
6710: 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e  (or, more common
6720: 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f  ly, a subclass o
6730: 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
6740: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20  3_file] object) 
6750: 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74  with a pointer t
6760: 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  o an instance of
6770: 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a   this object..**
6780: 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   This object def
6790: 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73  ines the methods
67a0: 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d   used to perform
67b0: 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69   various operati
67c0: 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74  ons.** against t
67d0: 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70  he open file rep
67e0: 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20  resented by the 
67f0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6800: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  bject..**.** If 
6810: 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64  the xOpen method
6820: 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65   sets the sqlite
6830: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
6840: 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61  element .** to a
6850: 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
6860: 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  r, then the sqli
6870: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78  te3_io_methods.x
6880: 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20  Close method.** 
6890: 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65  may be invoked e
68a0: 76 65 6e 20 69 66 20 74 68 65 20 78 4f 70 65 6e  ven if the xOpen
68b0: 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69   reported that i
68c0: 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a  t failed.  The.*
68d0: 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72  * only way to pr
68e0: 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20  event a call to 
68f0: 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67  xClose following
6900: 20 61 20 66 61 69 6c 65 64 20 78 4f 70 65 6e 0a   a failed xOpen.
6910: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 78 4f  ** is for the xO
6920: 70 65 6e 20 74 6f 20 73 65 74 20 74 68 65 20 73  pen to set the s
6930: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
6940: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 74 6f 20  hods element to 
6950: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
6960: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
6970: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
6980: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
6990: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
69a0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
69b0: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
69c0: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
69d0: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
69e0: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
69f0: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
6a00: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
6a10: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
6a20: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
6a30: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
6a40: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
6a50: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
6a60: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
6a70: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
6a80: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
6a90: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
6aa0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
6ab0: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
6ac0: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
6ad0: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
6ae0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6af0: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
6b00: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
6b10: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
6b20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
6b30: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
6b40: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
6b50: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
6b60: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
6b70: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
6b80: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
6b90: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
6ba0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
6bb0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
6bc0: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
6bd0: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
6be0: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
6bf0: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
6c00: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
6c10: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
6c20: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
6c30: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
6c40: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
6c50: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
6c60: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
6c70: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
6c80: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
6c90: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
6ca0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
6cb0: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
6cc0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
6cd0: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
6ce0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
6cf0: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
6d00: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
6d10: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
6d20: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
6d30: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
6d40: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
6d50: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
6d60: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
6d70: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
6d80: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
6d90: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
6da0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
6db0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
6dc0: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
6dd0: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
6de0: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
6df0: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
6e00: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
6e10: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
6e20: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
6e30: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
6e40: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
6e50: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
6e60: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
6e70: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
6e80: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
6e90: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
6ea0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
6eb0: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
6ec0: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
6ed0: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
6ee0: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
6ef0: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
6f00: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
6f10: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
6f20: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
6f30: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
6f40: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
6f50: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
6f60: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
6f70: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
6f80: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
6f90: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
6fa0: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
6fb0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
6fc0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
6fd0: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
6fe0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
6ff0: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
7000: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
7010: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7020: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7030: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7040: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7050: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
7060: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
7070: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
7080: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
7090: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
70a0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
70b0: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
70c0: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
70d0: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
70e0: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
70f0: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
7100: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
7110: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
7120: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
7130: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
7140: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
7150: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
7160: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
7170: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7180: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7190: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
71a0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
71b0: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
71c0: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
71d0: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
71e0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
71f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7200: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7210: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7220: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
7230: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7240: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
7250: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7260: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
7270: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7280: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7290: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
72a0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
72b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
72c0: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
72d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
72e0: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
72f0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7300: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
7310: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7320: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
7330: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7340: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
7350: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
7360: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7370: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
7380: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
7390: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
73a0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
73b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
73c0: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
73d0: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
73e0: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
73f0: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
7400: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
7410: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
7420: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
7430: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
7440: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
7450: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
7460: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7470: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
7480: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
7490: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
74a0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
74b0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
74c0: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
74d0: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
74e0: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
74f0: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
7500: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
7510: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
7520: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
7530: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
7540: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
7550: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
7560: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
7570: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
7580: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
7590: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
75a0: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
75b0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
75c0: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
75d0: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
75e0: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
75f0: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
7600: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
7610: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
7620: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7630: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
7640: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
7650: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
7660: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
7670: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
7680: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
7690: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
76a0: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
76b0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
76c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
76d0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
76e0: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
76f0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
7700: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
7710: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
7720: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
7730: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
7740: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
7750: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
7760: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
7770: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
7780: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
7790: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
77a0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
77b0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
77c0: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
77d0: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
77e0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
77f0: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
7800: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
7810: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
7820: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
7830: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
7840: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
7850: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
7860: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
7870: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
7880: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
7890: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
78a0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
78b0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
78c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
78d0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
78e0: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
78f0: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
7900: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
7910: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
7920: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
7930: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7940: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
7950: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
7960: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
7970: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
7980: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
7990: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
79a0: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
79b0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
79c0: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
79d0: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
79e0: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
79f0: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
7a00: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
7a10: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
7a20: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
7a30: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
7a40: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
7a50: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
7a60: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7a70: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
7a80: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
7a90: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
7aa0: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f  version 2 */.  /
7ab0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
7ac0: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
7ad0: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
7ae0: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
7af0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
7b00: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
7b10: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
7b20: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
7b30: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
7b40: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
7b50: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
7b60: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
7b70: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
7b80: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
7b90: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
7ba0: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
7bb0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
7bc0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
7bd0: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
7be0: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
7bf0: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
7c00: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
7c10: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
7c20: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
7c30: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
7c40: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
7c50: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
7c60: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
7c70: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7c80: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
7c90: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
7ca0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7cb0: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
7cc0: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
7cd0: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
7ce0: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
7cf0: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
7d00: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
7d10: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
7d20: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
7d30: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
7d40: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
7d50: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
7d60: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
7d70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
7d80: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
7d90: 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  NT] opcode is us
7da0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20  ed by SQLite to 
7db0: 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20  give the VFS.** 
7dc0: 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20  layer a hint of 
7dd0: 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61  how large the da
7de0: 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c  tabase file will
7df0: 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69   grow to be duri
7e00: 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  ng the.** curren
7e10: 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20  t transaction.  
7e20: 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74  This hint is not
7e30: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
7e40: 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69  e accurate but i
7e50: 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c  t.** is often cl
7e60: 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c  ose.  The underl
7e70: 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63  ying VFS might c
7e80: 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f  hoose to preallo
7e90: 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  cate database.**
7ea0: 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65   file space base
7eb0: 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69  d on this hint i
7ec0: 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20  n order to help 
7ed0: 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61  writes to the da
7ee0: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72  tabase.** file r
7ef0: 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a  un faster..**.**
7f00: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
7f10: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
7f20: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
7f30: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
7f40: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
7f50: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
7f60: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
7f70: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
7f80: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
7f90: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
7fa0: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
7fb0: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
7fc0: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
7fd0: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
7fe0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
7ff0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
8000: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
8010: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
8020: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
8030: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
8040: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
8050: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
8060: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
8070: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8080: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8090: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
80a0: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
80b0: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
80c0: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
80d0: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ems..**.** The [
80e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
80f0: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
8100: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
8110: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
8120: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
8130: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
8140: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
8150: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
8160: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
8170: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
8180: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8190: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
81a0: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
81b0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
81c0: 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ..**.** ^(The [S
81d0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
81e0: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
81f0: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
8200: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
8210: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
8220: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
8230: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
8240: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
8250: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
8260: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8270: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
8280: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
8290: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
82a0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
82b0: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
82c0: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
82d0: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
82e0: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
82f0: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
8300: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
8310: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
8320: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
8330: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
8340: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
8350: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
8360: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
8370: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
8380: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
8390: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
83a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
83b0: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
83c0: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
83d0: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
83e0: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
83f0: 65 63 69 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a  ecilized VFSes.*
8400: 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  * that do requir
8410: 65 20 69 74 2e 20 20 0a 2a 2f 0a 23 64 65 66 69  e it.  .*/.#defi
8420: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
8430: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
8440: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
8450: 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_GET_LOCKPROXYF
8460: 49 4c 45 20 20 20 20 20 20 32 0a 23 64 65 66 69  ILE      2.#defi
8470: 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f  ne SQLITE_SET_LO
8480: 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20  CKPROXYFILE     
8490: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
84a0: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
84b0: 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69           4.#defi
84c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
84d0: 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20  SIZE_HINT       
84e0: 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
84f0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
8500: 5a 45 20 20 20 20 20 20 20 36 0a 23 64 65 66 69  ZE       6.#defi
8510: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
8520: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
8530: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
8540: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
8550: 54 54 45 44 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  TTED     8.../*.
8560: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
8570: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
8580: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
8590: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
85a0: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
85b0: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
85c0: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
85d0: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
85e0: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
85f0: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
8600: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
8610: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
8620: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
8630: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
8640: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
8650: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
8660: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
8670: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
8680: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
8690: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
86a0: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
86b0: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
86c0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
86d0: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
86e0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
86f0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
8700: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
8710: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
8720: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
8730: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
8740: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
8750: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
8760: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
8770: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
8780: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
8790: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
87a0: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
87b0: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
87c0: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
87d0: 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  "..**.** The val
87e0: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
87f0: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
8800: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
8810: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
8820: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
8830: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
8840: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
8850: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
8860: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
8870: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
8880: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
8890: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
88a0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
88b0: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
88c0: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
88d0: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
88e0: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
88f0: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
8900: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
8910: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
8920: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
8930: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
8940: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
8950: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
8960: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
8970: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
8980: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
8990: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
89a0: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
89b0: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
89c0: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
89d0: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
89e0: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
89f0: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
8a00: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
8a10: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
8a20: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
8a30: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
8a40: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
8a50: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
8a60: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
8a70: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
8a80: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
8a90: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
8aa0: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
8ab0: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
8ac0: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
8ad0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
8ae0: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
8af0: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
8b00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
8b10: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
8b20: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
8b30: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
8b40: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
8b50: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
8b60: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
8b70: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
8b80: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
8b90: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
8ba0: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
8bb0: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
8bc0: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
8bd0: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
8be0: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
8bf0: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
8c00: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
8c10: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
8c20: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
8c30: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
8c40: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
8c50: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
8c60: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
8c70: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
8c80: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
8c90: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
8ca0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
8cb0: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
8cc0: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
8cd0: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
8ce0: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
8cf0: 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  **.** ^SQLite gu
8d00: 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
8d10: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
8d20: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a  meter to xOpen.*
8d30: 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55  * is either a NU
8d40: 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74  LL pointer or st
8d50: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ring obtained.**
8d60: 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e   from xFullPathn
8d70: 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70  ame() with an op
8d80: 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64  tional suffix ad
8d90: 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75  ded..** ^If a su
8da0: 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f  ffix is added to
8db0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
8dc0: 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c  arameter, it wil
8dd0: 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20  l.** consist of 
8de0: 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61  a single "-" cha
8df0: 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20  racter followed 
8e00: 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a  by no more than.
8e10: 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65 72  ** 10 alphanumer
8e20: 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68  ic and/or "-" ch
8e30: 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51  aracters..** ^SQ
8e40: 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61  Lite further gua
8e50: 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20  rantees that.** 
8e60: 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  the string will 
8e70: 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63  be valid and unc
8e80: 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c  hanged until xCl
8e90: 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c  ose() is.** call
8ea0: 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74  ed. Because of t
8eb0: 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
8ec0: 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71  ence,.** the [sq
8ed0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20  lite3_file] can 
8ee0: 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70  safely store a p
8ef0: 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ointer to the.**
8f00: 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20   filename if it 
8f10: 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65  needs to remembe
8f20: 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66  r the filename f
8f30: 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a  or some reason..
8f40: 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e  ** If the zFilen
8f50: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
8f60: 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c   xOpen is a NULL
8f70: 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f   pointer then xO
8f80: 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65  pen.** must inve
8f90: 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f  nt its own tempo
8fa0: 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68  rary name for th
8fb0: 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76  e file.  ^Whenev
8fc0: 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65  er the .** xFile
8fd0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69  name parameter i
8fe0: 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61  s NULL it will a
8ff0: 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20  lso be the case 
9000: 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67  that the.** flag
9010: 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c  s parameter will
9020: 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45   include [SQLITE
9030: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
9040: 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  OSE]..**.** The 
9050: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
9060: 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64  o xOpen() includ
9070: 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20  es all bits set 
9080: 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20  in.** the flags 
9090: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
90a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e  ite3_open_v2()].
90b0: 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33    Or if [sqlite3
90c0: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b  _open()].** or [
90d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
90e0: 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  ] is used, then 
90f0: 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61  flags includes a
9100: 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49  t least.** [SQLI
9110: 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
9120: 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
9130: 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49  N_CREATE]. .** I
9140: 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20  f xOpen() opens 
9150: 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79  a file read-only
9160: 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70   then it sets *p
9170: 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69  OutFlags to.** i
9180: 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f  nclude [SQLITE_O
9190: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20  PEN_READONLY].  
91a0: 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70  Other bits in *p
91b0: 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20  OutFlags may be 
91c0: 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c  set..**.** ^(SQL
91d0: 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64  ite will also ad
91e0: 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  d one of the fol
91f0: 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20  lowing flags to 
9200: 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63  the xOpen().** c
9210: 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  all, depending o
9220: 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69  n the object bei
9230: 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a  ng opened:.**.**
9240: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b   <ul>.** <li>  [
9250: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
9260: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
9270: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
9280: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
9290: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
92a0: 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  EMP_DB].** <li> 
92b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
92c0: 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  MP_JOURNAL].** <
92d0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
92e0: 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a  N_TRANSIENT_DB].
92f0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
9300: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
9310: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
9320: 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a  TE_OPEN_MASTER_J
9330: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
9340: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41   [SQLITE_OPEN_WA
9350: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  L].** </ul>)^.**
9360: 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f  .** The file I/O
9370: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
9380: 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65  can use the obje
9390: 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f  ct type flags to
93a0: 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77  .** change the w
93b0: 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68  ay it deals with
93c0: 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61   files.  For exa
93d0: 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61  mple, an applica
93e0: 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65  tion.** that doe
93f0: 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74  s not care about
9400: 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20   crash recovery 
9410: 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68  or rollback migh
9420: 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70  t make.** the op
9430: 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20  en of a journal 
9440: 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57  file a no-op.  W
9450: 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f  rites to this jo
9460: 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61  urnal would.** a
9470: 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61  lso be no-ops, a
9480: 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74  nd any attempt t
9490: 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e  o read the journ
94a0: 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a  al would return.
94b0: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e  ** SQLITE_IOERR.
94c0: 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65    Or the impleme
94d0: 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ntation might re
94e0: 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64  cognize that a d
94f0: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
9500: 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61  will be doing pa
9510: 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f  ge-aligned secto
9520: 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74  r reads and writ
9530: 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a  es in a random.*
9540: 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20  * order and set 
9550: 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79  up its I/O subsy
9560: 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79  stem accordingly
9570: 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  ..**.** SQLite m
9580: 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e  ight also add on
9590: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
95a0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
95b0: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a  xOpen method:.**
95c0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
95d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
95e0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
95f0: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45  <li> [SQLITE_OPE
9600: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20  N_EXCLUSIVE].** 
9610: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
9620: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
9630: 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67  ETEONCLOSE] flag
9640: 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20   means the file 
9650: 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c  should be.** del
9660: 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20  eted when it is 
9670: 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53  closed.  ^The [S
9680: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
9690: 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c  EONCLOSE].** wil
96a0: 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d  l be set for TEM
96b0: 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20  P databases and 
96c0: 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20  their journals, 
96d0: 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74  transient.** dat
96e0: 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a  abases, and subj
96f0: 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ournals..**.** ^
9700: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
9710: 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67  _EXCLUSIVE] flag
9720: 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20   is always used 
9730: 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a  in conjunction.*
9740: 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49  * with the [SQLI
9750: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20  TE_OPEN_CREATE] 
9760: 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20  flag, which are 
9770: 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a  both directly.**
9780: 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68   analogous to th
9790: 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43  e O_EXCL and O_C
97a0: 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68  REAT flags of th
97b0: 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a  e POSIX open().*
97c0: 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49  * API.  The SQLI
97d0: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
97e0: 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69  E flag, when pai
97f0: 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a  red with the .**
9800: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
9810: 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20  ATE, is used to 
9820: 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69  indicate that fi
9830: 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73  le should always
9840: 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20  .** be created, 
9850: 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61  and that it is a
9860: 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c  n error if it al
9870: 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a  ready exists..**
9880: 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69   It is <i>not</i
9890: 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  > used to indica
98a0: 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  te the file shou
98b0: 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a  ld be opened .**
98c0: 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61   for exclusive a
98d0: 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74  ccess..**.** ^At
98e0: 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20   least szOsFile 
98f0: 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  bytes of memory 
9900: 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79  are allocated by
9910: 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f   SQLite.** to ho
9920: 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33  ld the  [sqlite3
9930: 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65  _file] structure
9940: 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74   passed as the t
9950: 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  hird.** argument
9960: 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20   to xOpen.  The 
9970: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65  xOpen method doe
9980: 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a  s not have to.**
9990: 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74   allocate the st
99a0: 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75  ructure; it shou
99b0: 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20  ld just fill it 
99c0: 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a  in.  Note that.*
99d0: 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  * the xOpen meth
99e0: 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20  od must set the 
99f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
9a00: 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a  thods to either.
9a10: 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69  ** a valid [sqli
9a20: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
9a30: 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c  object or to NUL
9a40: 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64  L.  xOpen must d
9a50: 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69  o.** this even i
9a60: 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73  f the open fails
9a70: 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74  .  SQLite expect
9a80: 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74  s that the sqlit
9a90: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
9aa0: 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c  .** element will
9ab0: 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20   be valid after 
9ac0: 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65  xOpen returns re
9ad0: 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20  gardless of the 
9ae0: 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61  success.** or fa
9af0: 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70  ilure of the xOp
9b00: 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  en call..**.** ^
9b10: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
9b20: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
9b30: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
9b40: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
9b50: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
9b60: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
9b70: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
9b80: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
9b90: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
9ba0: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
9bb0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
9bc0: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
9bd0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
9be0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
9bf0: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
9c00: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
9c10: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
9c20: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
9c30: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
9c40: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
9c50: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
9c60: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
9c70: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
9c80: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
9c90: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
9ca0: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
9cb0: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
9cc0: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
9cd0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
9ce0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
9cf0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
9d00: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
9d10: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
9d20: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
9d30: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
9d40: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
9d50: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
9d60: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
9d70: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
9d80: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
9d90: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
9da0: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
9db0: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
9dc0: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
9dd0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
9de0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
9df0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
9e00: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
9e10: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
9e20: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
9e30: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
9e40: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
9e50: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
9e60: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
9e70: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
9e80: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
9e90: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
9ea0: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
9eb0: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
9ec0: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
9ed0: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
9ee0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
9ef0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
9f00: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
9f10: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
9f20: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
9f30: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
9f40: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
9f50: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
9f60: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
9f70: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
9f80: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
9f90: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
9fa0: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
9fb0: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
9fc0: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
9fd0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
9fe0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
9ff0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
a000: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
a010: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
a020: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
a030: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
a040: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
a050: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
a060: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
a070: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
a080: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
a090: 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38 36   multipled by 86
a0a0: 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62  400000 (the numb
a0b0: 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
a0c0: 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68  ds in .** a 24-h
a0d0: 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e  our day).  .** ^
a0e0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
a0f0: 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65  the xCurrentTime
a100: 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74  Int64() method t
a110: 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e  o get the curren
a120: 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69  t.** date and ti
a130: 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f  me if that metho
a140: 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28  d is available (
a150: 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32  if iVersion is 2
a160: 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20   or .** greater 
a170: 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  and the function
a180: 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
a190: 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66  NULL) and will f
a1a0: 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78  all back.** to x
a1b0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66  CurrentTime() if
a1c0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
a1d0: 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61  64() is unavaila
a1e0: 62 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ble..*/.typedef 
a1f0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
a200: 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a  fs sqlite3_vfs;.
a210: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
a220: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
a230: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
a240: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
a250: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
a260: 72 65 6e 74 6c 79 20 32 29 20 2a 2f 0a 20 20 69  rently 2) */.  i
a270: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
a280: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
a290: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
a2a0: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
a2b0: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
a2c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
a2d0: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
a2e0: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
a2f0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
a300: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
a310: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
a320: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
a330: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
a340: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
a350: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
a360: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
a370: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
a380: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
a390: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
a3a0: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
a3b0: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
a3c0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
a3d0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
a3e0: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
a3f0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
a400: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
a410: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
a420: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
a430: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
a440: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
a450: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
a460: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
a470: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
a480: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
a490: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
a4a0: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
a4b0: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
a4c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
a4d0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
a4e0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
a4f0: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
a500: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
a510: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
a520: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
a530: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
a540: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
a550: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
a560: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
a570: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
a580: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
a590: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
a5a0: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
a5b0: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
a5c0: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
a5d0: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
a5e0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
a5f0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
a600: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
a610: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
a620: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
a630: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
a640: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
a650: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
a660: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
a670: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
a680: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
a690: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
a6a0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
a6b0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
a6c0: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
a6d0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
a6e0: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
a6f0: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
a700: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
a710: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
a720: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
a730: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
a740: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
a750: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
a760: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
a770: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
a780: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
a790: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
a7a0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
a7b0: 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
a7c0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
a7d0: 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
a7e0: 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
a7f0: 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
a800: 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
a810: 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
a820: 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
a830: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a840: 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
a850: 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
a860: 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
a870: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
a880: 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
a890: 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
a8a0: 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
a8b0: 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
a8c0: 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
a8d0: 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
a8e0: 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
a8f0: 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
a900: 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
a910: 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
a920: 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
a930: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
a940: 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
a950: 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
a960: 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
a970: 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
a980: 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
a990: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
a9a0: 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
a9b0: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
a9c0: 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65  whether the name
a9d0: 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62  d directory is b
a9e0: 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
a9f0: 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e   writable.** (in
aa00: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
aa10: 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64   files can be ad
aa20: 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e  ded, removed, an
aa30: 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e  d renamed within
aa40: 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72  .** the director
aa50: 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  y)..** The SQLIT
aa60: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
aa70: 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63  TE constant is c
aa80: 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e  urrently used on
aa90: 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65  ly by the.** [te
aaa0: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
aab0: 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75  ry pragma], thou
aac0: 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68  gh this could ch
aad0: 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
aae0: 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
aaf0: 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53  QLite..** With S
ab00: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
ab10: 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
ab20: 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
ab30: 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
ab40: 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54   is readable.  T
ab50: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
ab60: 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69  _READ constant i
ab70: 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75  s.** currently u
ab80: 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74  nused, though it
ab90: 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69   might be used i
aba0: 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61  n a future relea
abb0: 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
abc0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
abd0: 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
abe0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
abf0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ac00: 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65  WRITE 1   /* Use
ac10: 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70  d by PRAGMA temp
ac20: 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
ac30: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
ac40: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
ac50: 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65      2   /* Unuse
ac60: 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
ac70: 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
ac80: 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53  the xShmLock VFS
ac90: 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
aca0: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
acb0: 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65  tants define the
acc0: 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67   various locking
acd0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
ace0: 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53  llowed by the xS
acf0: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66  hmLock method of
ad00: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
ad10: 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66  hods].  The.** f
ad20: 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65  ollowing are the
ad30: 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62   only legal comb
ad40: 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67  inations of flag
ad50: 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d  s to the.** xShm
ad60: 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Lock method:.**.
ad70: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
ad80: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
ad90: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
ada0: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
adb0: 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
adc0: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
add0: 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
ade0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
adf0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
ae00: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
ae10: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
ae20: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
ae30: 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  USIVE.** </ul>.*
ae40: 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b  *.** When unlock
ae50: 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48  ing, the same SH
ae60: 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56  ARED or EXCLUSIV
ae70: 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73  E flag must be s
ae80: 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61  upplied as.** wa
ae90: 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63  s given no the c
aea0: 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63  orresponding loc
aeb0: 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  k.  .**.** The x
aec0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63  ShmLock method c
aed0: 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  an transition be
aee0: 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
aef0: 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20  nd SHARED or.** 
af00: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
af10: 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20   and EXCLUSIVE. 
af20: 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73   It cannot trans
af30: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48  ition between SH
af40: 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c  ARED.** and EXCL
af50: 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e  USIVE..*/.#defin
af60: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c  e SQLITE_SHM_UNL
af70: 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66  OCK       1.#def
af80: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  ine SQLITE_SHM_L
af90: 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64  OCK         2.#d
afa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
afb0: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a  _SHARED       4.
afc0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
afd0: 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  HM_EXCLUSIVE    
afe0: 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
aff0: 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c  F: Maximum xShmL
b000: 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20  ock index.**.** 
b010: 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
b020: 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  hod on [sqlite3_
b030: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20  io_methods] may 
b040: 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  use values.** be
b050: 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73  tween 0 and this
b060: 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20   upper bound as 
b070: 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67  its "offset" arg
b080: 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51  ument..** The SQ
b090: 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e  Lite core will n
b0a0: 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20  ever attempt to 
b0b0: 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61  acquire or relea
b0c0: 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74  se a.** lock out
b0d0: 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e  side of this ran
b0e0: 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge.*/.#define SQ
b0f0: 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20  LITE_SHM_NLOCK  
b100: 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20        8.../*.** 
b110: 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
b120: 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
b130: 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  Library.**.** ^T
b140: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
b150: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
b160: 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
b170: 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
b180: 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  y.  ^The sqlite3
b190: 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
b1a0: 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
b1b0: 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
b1c0: 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
b1d0: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
b1e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
b1f0: 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
b200: 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20  are designed to 
b210: 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69  aid in process i
b220: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
b230: 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e  d.** shutdown on
b240: 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
b250: 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20  s.  Workstation 
b260: 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69  applications usi
b270: 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72  ng.** SQLite nor
b280: 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65  mally do not nee
b290: 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68  d to invoke eith
b2a0: 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  er of these rout
b2b0: 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ines..**.** A ca
b2c0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
b2d0: 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
b2e0: 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
b2f0: 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
b300: 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
b310: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b320: 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
b330: 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
b340: 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
b350: 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
b360: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
b370: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b380: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
b390: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
b3a0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
b3b0: 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c  utdown().  ^(Onl
b3c0: 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
b3d0: 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
b3e0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
b3f0: 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
b400: 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
b410: 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
b420: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
b430: 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )^.**.** A call 
b440: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
b450: 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66  own() is an "eff
b460: 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
b470: 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  it is the first.
b480: 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
b490: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69  e3_shutdown() si
b4a0: 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c  nce the last sql
b4b0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b4c0: 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e  ).  ^(Only.** an
b4d0: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
b4e0: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
b4f0: 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
b500: 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
b510: 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  .** All other va
b520: 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  lid calls to sql
b530: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
b540: 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
b550: 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ops.)^.**.** The
b560: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b570: 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ize() interface 
b580: 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62  is threadsafe, b
b590: 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ut sqlite3_shutd
b5a0: 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e  own().** is not.
b5b0: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
b5c0: 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
b5d0: 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20  ce must only be 
b5e0: 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  called from a.**
b5f0: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
b600: 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62   All open [datab
b610: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
b620: 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20   must be closed 
b630: 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72  and all.** other
b640: 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65   SQLite resource
b650: 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f  s must be deallo
b660: 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69  cated prior to i
b670: 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
b680: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  e3_shutdown()..*
b690: 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
b6a0: 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65   things, ^sqlite
b6b0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77  3_initialize() w
b6c0: 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  ill invoke.** sq
b6d0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
b6e0: 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71    Similarly, ^sq
b6f0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
b700: 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  .** will invoke 
b710: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
b720: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
b730: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
b740: 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
b750: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
b760: 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66   success..** ^If
b770: 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
b780: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
b790: 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
b7a0: 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
b7b0: 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
b7c0: 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
b7d0: 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
b7e0: 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
b7f0: 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
b800: 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
b810: 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
b820: 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
b830: 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
b840: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
b850: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
b860: 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
b870: 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
b880: 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
b890: 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
b8a0: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
b8b0: 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
b8c0: 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
b8d0: 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
b8e0: 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
b8f0: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
b900: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
b910: 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
b920: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
b930: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
b940: 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
b950: 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
b960: 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
b970: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
b980: 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
b990: 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
b9a0: 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
b9b0: 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66  y.  ^However, if
b9c0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
b9d0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
b9e0: 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
b9f0: 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
ba00: 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
ba10: 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
ba20: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
ba30: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
ba40: 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
ba50: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
ba60: 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
ba70: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
ba80: 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
ba90: 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
baa0: 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
bab0: 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
bac0: 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
bad0: 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
bae0: 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
baf0: 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
bb00: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
bb10: 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
bb20: 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
bb30: 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
bb40: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
bb50: 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
bb60: 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
bb70: 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
bb80: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
bb90: 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
bba0: 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
bbb0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
bbc0: 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
bbd0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
bbe0: 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
bbf0: 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
bc00: 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
bc10: 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
bc20: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
bc30: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
bc40: 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
bc50: 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
bc60: 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
bc70: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
bc80: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
bc90: 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
bca0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
bcb0: 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
bcc0: 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
bcd0: 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
bce0: 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
bcf0: 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
bd00: 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
bd10: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
bd20: 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
bd30: 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
bd40: 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
bd50: 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
bd60: 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
bd70: 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
bd80: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
bd90: 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
bda0: 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
bdb0: 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
bdc0: 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
bdd0: 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
bde0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
bdf0: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
be00: 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
be10: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
be20: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
be30: 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
be40: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
be50: 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
be60: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
be70: 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
be80: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
be90: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
bea0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
beb0: 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
bec0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
bed0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
bee0: 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
bef0: 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
bf00: 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
bf10: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
bf20: 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
bf30: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
bf40: 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
bf50: 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
bf60: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
bf70: 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
bf80: 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
bf90: 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
bfa0: 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
bfb0: 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
bfc0: 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
bfd0: 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
bfe0: 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
bff0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
c000: 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
c010: 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
c020: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
c030: 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
c040: 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
c050: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
c060: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
c070: 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
c080: 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
c090: 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
c0a0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
c0b0: 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
c0c0: 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
c0d0: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
c0e0: 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
c0f0: 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
c100: 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
c110: 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
c120: 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
c130: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
c140: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c150: 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  e(void);.SQLITE_
c160: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
c170: 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a  shutdown(void);.
c180: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
c190: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
c1a0: 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
c1b0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f   int sqlite3_os_
c1c0: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
c1d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
c1e0: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
c1f0: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
c200: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
c210: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
c220: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
c230: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
c240: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
c250: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
c260: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
c270: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
c280: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
c290: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
c2a0: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
c2b0: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
c2c0: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
c2d0: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
c2e0: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
c2f0: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
c300: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
c310: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
c320: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
c330: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
c340: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
c350: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
c360: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
c370: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
c380: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
c390: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
c3a0: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
c3b0: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
c3c0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
c3d0: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
c3e0: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
c3f0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
c400: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
c410: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
c420: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
c430: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
c440: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
c450: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
c460: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
c470: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c480: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
c490: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
c4a0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
c4b0: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
c4c0: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
c4d0: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
c4e0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
c4f0: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
c500: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
c510: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
c520: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
c530: 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
c540: 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
c550: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
c560: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
c570: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
c580: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
c590: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
c5a0: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
c5b0: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
c5c0: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
c5d0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
c5e0: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
c5f0: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
c600: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
c610: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
c620: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
c630: 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
c640: 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
c650: 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
c660: 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
c670: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
c680: 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
c690: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51  nding on the [SQ
c6a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
c6b0: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
c6c0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
c6d0: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
c6e0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
c6f0: 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
c700: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
c710: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
c720: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
c730: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
c740: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
c750: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
c760: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
c770: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
c780: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
c790: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
c7a0: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
c7b0: 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  de]..*/.SQLITE_A
c7c0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
c7d0: 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
c7e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
c7f0: 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
c800: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
c810: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
c820: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
c830: 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
c840: 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
c850: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
c860: 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
c870: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
c880: 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
c890: 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
c8a0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
c8b0: 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
c8c0: 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
c8d0: 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
c8e0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
c8f0: 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
c900: 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
c910: 6d 65 6e 74 29 2e 20 20 54 68 65 0a 2a 2a 20 73  ment).  The.** s
c920: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
c930: 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 68 6f  () interface sho
c940: 75 6c 64 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  uld only be used
c950: 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74   immediately aft
c960: 65 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  er.** the databa
c970: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
c980: 20 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b   created using [
c990: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
c9a0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
c9b0: 6e 31 36 28 29 5d 2c 20 6f 72 20 5b 73 71 6c 69  n16()], or [sqli
c9c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
c9d0: 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f   .**.** The seco
c9e0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
c9f0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
ca00: 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
ca10: 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  e.** configurati
ca20: 6f 6e 20 76 65 72 62 20 2d 20 61 6e 20 69 6e 74  on verb - an int
ca30: 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 69  eger code that i
ca40: 6e 64 69 63 61 74 65 73 20 77 68 61 74 0a 2a 2a  ndicates what.**
ca50: 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
ca60: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
ca70: 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
ca80: 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 54 68 65  nfigured..** The
ca90: 20 6f 6e 6c 79 20 63 68 6f 69 63 65 20 66 6f 72   only choice for
caa0: 20 74 68 69 73 20 76 61 6c 75 65 20 69 73 20 5b   this value is [
cab0: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
cac0: 4c 4f 4f 4b 41 53 49 44 45 5d 2e 0a 2a 2a 20 4e  LOOKASIDE]..** N
cad0: 65 77 20 76 65 72 62 73 20 61 72 65 20 6c 69 6b  ew verbs are lik
cae0: 65 6c 79 20 74 6f 20 62 65 20 61 64 64 65 64 20  ely to be added 
caf0: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
cb00: 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
cb10: 20 41 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   Additional argu
cb20: 6d 65 6e 74 73 20 64 65 70 65 6e 64 20 6f 6e 20  ments depend on 
cb30: 74 68 65 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20  the verb..**.** 
cb40: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
cb50: 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65  3_db_config() re
cb60: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
cb70: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
cb80: 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e   the call is con
cb90: 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66  sidered successf
cba0: 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ul..*/.SQLITE_AP
cbb0: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  I int sqlite3_db
cbc0: 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
cbd0: 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
cbe0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
cbf0: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
cc00: 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
cc10: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
cc20: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
cc30: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
cc40: 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
cc50: 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
cc60: 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
cc70: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
cc80: 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
cc90: 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
cca0: 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
ccb0: 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
ccc0: 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
ccd0: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
cce0: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
ccf0: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
cd00: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
cd10: 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
cd20: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
cd30: 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
cd40: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
cd50: 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
cd60: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
cd70: 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
cd80: 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
cd90: 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
cda0: 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
cdb0: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
cdc0: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
cdd0: 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
cde0: 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
cdf0: 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
ce00: 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
ce10: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
ce20: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
ce30: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
ce40: 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
ce50: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
ce60: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
ce70: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
ce80: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
ce90: 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
cea0: 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
ceb0: 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
cec0: 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
ced0: 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
cee0: 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
cef0: 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
cf00: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
cf10: 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
cf20: 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
cf30: 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
cf40: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
cf50: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
cf60: 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
cf70: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
cf80: 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
cf90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
cfa0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
cfb0: 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
cfc0: 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
cfd0: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
cfe0: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
cff0: 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
d000: 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
d010: 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
d020: 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
d030: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
d040: 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
d050: 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
d060: 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
d070: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
d080: 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20  alloc and xFree 
d090: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
d0a0: 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
d0b0: 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
d0c0: 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
d0d0: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
d0e0: 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20  library..** The 
d0f0: 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20  xRealloc method 
d100: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72  must work like r
d110: 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68  ealloc() from th
d120: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
d130: 72 61 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65  rary.** with the
d140: 20 65 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20   exception that 
d150: 69 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  if the second ar
d160: 67 75 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c  gument to xReall
d170: 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78  oc is zero,.** x
d180: 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20  Realloc must be 
d190: 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73  a no-op - it mus
d1a0: 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e  t not perform an
d1b0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a  y allocation or.
d1c0: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e  ** deallocation.
d1d0: 20 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e    ^SQLite guaran
d1e0: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
d1f0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
d200: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
d210: 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
d220: 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
d230: 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
d240: 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69  dup..** And so i
d250: 6e 20 63 61 73 65 73 20 77 68 65 72 65 20 78 52  n cases where xR
d260: 6f 75 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65  oundup always re
d270: 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65  turns a positive
d280: 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61   number,.** xRea
d290: 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d  lloc can perform
d2a0: 20 65 78 61 63 74 6c 79 20 61 73 20 74 68 65 20   exactly as the 
d2b0: 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79  standard library
d2c0: 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a   realloc() and.*
d2d0: 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f  * still be in co
d2e0: 6d 70 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68  mpliance with th
d2f0: 69 73 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  is specification
d300: 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
d310: 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
d320: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
d330: 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
d340: 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
d350: 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
d360: 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
d370: 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
d380: 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
d390: 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
d3a0: 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
d3b0: 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
d3c0: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
d3d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
d3e0: 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
d3f0: 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
d400: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
d410: 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
d420: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
d430: 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
d440: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
d450: 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
d460: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
d470: 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
d480: 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
d490: 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
d4a0: 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
d4b0: 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
d4c0: 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
d4d0: 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
d4e0: 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
d4f0: 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
d500: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
d510: 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
d520: 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
d530: 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
d540: 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
d550: 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
d560: 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
d570: 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
d580: 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
d590: 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
d5a0: 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
d5b0: 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
d5c0: 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
d5d0: 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
d5e0: 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
d5f0: 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78  ocator.  (For ex
d600: 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
d610: 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
d620: 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
d630: 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
d640: 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
d650: 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
d660: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
d670: 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
d680: 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
d690: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
d6a0: 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
d6b0: 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
d6c0: 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
d6d0: 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
d6e0: 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
d6f0: 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
d700: 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
d710: 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
d720: 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
d730: 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
d740: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
d750: 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
d760: 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
d770: 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
d780: 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
d790: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
d7a0: 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
d7b0: 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
d7c0: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
d7d0: 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
d7e0: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
d7f0: 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
d800: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
d810: 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
d820: 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
d830: 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
d840: 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
d850: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
d860: 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
d870: 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
d880: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
d890: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
d8a0: 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
d8b0: 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
d8c0: 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
d8d0: 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
d8e0: 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
d8f0: 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
d900: 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
d910: 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
d920: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
d930: 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
d940: 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
d950: 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
d960: 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
d970: 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
d980: 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
d990: 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
d9a0: 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
d9b0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
d9c0: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
d9d0: 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
d9e0: 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
d9f0: 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
da00: 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
da10: 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
da20: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
da30: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
da40: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
da50: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
da60: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
da70: 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
da80: 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
da90: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
daa0: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
dab0: 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
dac0: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
dad0: 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
dae0: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
daf0: 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
db00: 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
db10: 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
db20: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
db30: 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
db40: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
db50: 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
db60: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
db70: 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
db80: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
db90: 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
dba0: 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
dbb0: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
dbc0: 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
dbd0: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
dbe0: 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
dbf0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
dc00: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
dc10: 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
dc20: 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
dc30: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
dc40: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
dc50: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
dc60: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
dc70: 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
dc80: 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
dc90: 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
dca0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
dcb0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
dcc0: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
dcd0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
dce0: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
dcf0: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
dd00: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
dd10: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
dd20: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
dd30: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
dd40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
dd50: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
dd60: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
dd70: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
dd80: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
dd90: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
dda0: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
ddb0: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
ddc0: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
ddd0: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
dde0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
ddf0: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
de00: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
de10: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
de20: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
de30: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
de40: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
de50: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
de60: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
de70: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
de80: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
de90: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
dea0: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
deb0: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
dec0: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
ded0: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
dee0: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
def0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
df00: 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
df10: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
df20: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
df30: 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
df40: 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
df50: 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
df60: 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
df70: 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
df80: 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
df90: 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
dfa0: 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
dfb0: 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
dfc0: 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
dfd0: 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
dfe0: 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
dff0: 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
e000: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
e010: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
e020: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
e030: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
e040: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
e050: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
e060: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
e070: 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
e080: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
e090: 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
e0a0: 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
e0b0: 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
e0c0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e0d0: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
e0e0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
e0f0: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
e100: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
e110: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
e120: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
e130: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
e140: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
e150: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
e160: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
e170: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
e180: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
e190: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
e1a0: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
e1b0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
e1c0: 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
e1d0: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
e1e0: 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
e1f0: 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
e200: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e210: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
e220: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
e230: 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
e240: 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
e250: 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
e260: 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
e270: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
e280: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
e290: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
e2a0: 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
e2b0: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
e2c0: 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
e2d0: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
e2e0: 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
e2f0: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
e300: 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
e310: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
e320: 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
e330: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
e340: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
e350: 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
e360: 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
e370: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
e380: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
e390: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
e3a0: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
e3b0: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
e3c0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
e3d0: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
e3e0: 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
e3f0: 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
e400: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
e410: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
e420: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
e430: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
e440: 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
e450: 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
e460: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
e470: 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
e480: 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
e490: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
e4a0: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
e4b0: 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
e4c0: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
e4d0: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
e4e0: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
e4f0: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
e500: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
e510: 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
e520: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
e530: 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
e540: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
e550: 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
e560: 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
e570: 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
e580: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
e590: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
e5a0: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
e5b0: 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
e5c0: 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
e5d0: 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
e5e0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
e5f0: 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
e600: 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
e610: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
e620: 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
e630: 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
e640: 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
e650: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
e660: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
e670: 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
e680: 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
e690: 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
e6a0: 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
e6b0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
e6c0: 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
e6d0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
e6e0: 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
e6f0: 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
e700: 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
e710: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
e720: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
e730: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
e740: 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
e750: 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
e760: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
e770: 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
e780: 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
e790: 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
e7a0: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
e7b0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
e7c0: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
e7d0: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
e7e0: 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
e7f0: 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
e800: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
e810: 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
e820: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
e830: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
e840: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
e850: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
e860: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
e870: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
e880: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
e890: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
e8a0: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
e8b0: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
e8c0: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
e8d0: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
e8e0: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
e8f0: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
e900: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
e910: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
e920: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
e930: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
e940: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
e950: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
e960: 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
e970: 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
e980: 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
e990: 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
e9a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
e9b0: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
e9c0: 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
e9d0: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
e9e0: 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
e9f0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
ea00: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
ea10: 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
ea20: 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
ea30: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
ea40: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
ea50: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
ea60: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
ea70: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
ea80: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
ea90: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b  tructure.  The [
eaa0: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
eab0: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
eac0: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
ead0: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
eae0: 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
eaf0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
eb00: 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
eb10: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
eb20: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
eb30: 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
eb40: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
eb50: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
eb60: 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
eb70: 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
eb80: 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
eb90: 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
eba0: 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
ebb0: 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
ebc0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
ebd0: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
ebe0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
ebf0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
ec00: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
ec10: 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74  of type int, int
ec20: 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a  erpreted as a .*
ec30: 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  * boolean, which
ec40: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
ec50: 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74  bles the collect
ec60: 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ion of memory al
ec70: 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61  location .** sta
ec80: 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
ec90: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
eca0: 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
ecb0: 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a   disabled, the .
ecc0: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  ** following SQL
ecd0: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
ece0: 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
ecf0: 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
ed00: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
ed10: 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
ed20: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
ed30: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
ed40: 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
ed50: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
ed60: 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
ed70: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
ed80: 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a  ite3_status()].*
ed90: 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  *   </ul>)^.** ^
eda0: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
edb0: 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
edc0: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
edd0: 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74  ult unless SQLit
ede0: 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
edf0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
ee00: 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
ee10: 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  =0 in which case
ee20: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
ee30: 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
ee40: 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
ee50: 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64   default..** </d
ee60: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
ee70: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
ee80: 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
ee90: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
eea0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
eeb0: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
eec0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
eed0: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
eee0: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
eef0: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
ef00: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
ef10: 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
ef20: 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
ef30: 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
ef40: 65 20 73 63 72 61 63 68 20 61 6c 6c 6f 63 61 74  e scrach allocat
ef50: 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
ef60: 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
ef70: 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
ef80: 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
ef90: 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
efa0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
efb0: 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
efc0: 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
efd0: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
efe0: 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
eff0: 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73   16..** The firs
f000: 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
f010: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
f020: 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
f030: 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
f040: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
f050: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
f060: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
f070: 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74  e no more than t
f080: 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65  wo scratch buffe
f090: 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20  rs per thread.  
f0a0: 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62  So.** N should b
f0b0: 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74  e set to twice t
f0c0: 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
f0d0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
f0e0: 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  reads..** ^SQLit
f0f0: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
f100: 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62  uire a scratch b
f110: 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
f120: 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
f130: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
f140: 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53  page size. ^If S
f150: 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
f160: 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
f170: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
f180: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
f190: 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
f1a0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
f1b0: 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
f1c0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
f1d0: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
f1e0: 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
f1f0: 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a  ry needed.</dd>.
f200: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
f210: 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
f220: 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
f230: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
f240: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
f250: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
f260: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
f270: 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61   for.** the data
f280: 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20  base page cache 
f290: 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74  with the default
f2a0: 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
f2b0: 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  emenation.  .** 
f2c0: 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
f2d0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
f2e0: 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
f2f0: 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
f300: 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
f310: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
f320: 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
f330: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
f340: 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  ACHE option..** 
f350: 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
f360: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
f370: 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e  s option: A poin
f380: 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c  ter to 8-byte al
f390: 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c  igned.** memory,
f3a0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
f3b0: 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73  h page buffer (s
f3c0: 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  z), and the numb
f3d0: 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e  er of pages (N).
f3e0: 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
f3f0: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
f400: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
f410: 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
f420: 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
f430: 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
f440: 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c  12 and 32768) pl
f450: 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72  us a little extr
f460: 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  a for each.** pa
f470: 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
f480: 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a   page header siz
f490: 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79  e is 20 to 40 by
f4a0: 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  tes depending on
f4b0: 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63  .** the host arc
f4c0: 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20  hitecture.  ^It 
f4d0: 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
f4e0: 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
f4f0: 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f  ed memory,.** to
f500: 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c   make sz a littl
f510: 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68  e too large.  Th
f520: 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
f530: 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
f540: 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
f550: 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  n of at least sz
f560: 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
f570: 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
f580: 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
f590: 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
f5a0: 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
f5b0: 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73  t to satisfy its
f5c0: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  .** memory needs
f5d0: 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
f5e0: 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
f5f0: 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e  dds to cache.  ^
f600: 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
f610: 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
f620: 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
f630: 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
f640: 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
f650: 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
f660: 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
f670: 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
f680: 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
f690: 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
f6a0: 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
f6b0: 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
f6c0: 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65  ument must.** be
f6d0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
f6e0: 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f  -byte boundary o
f6f0: 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
f700: 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
f710: 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  ** will be undef
f720: 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ined.</dd>.**.**
f730: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f740: 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
f750: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
f760: 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
f770: 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
f780: 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  er that SQLite w
f790: 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61  ill use.** for a
f7a0: 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
f7b0: 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
f7c0: 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64  ion needs beyond
f7d0: 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a   those provided.
f7e0: 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ** for by [SQLIT
f7f0: 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
f800: 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f  ] and [SQLITE_CO
f810: 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
f820: 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
f830: 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41  ree arguments: A
f840: 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
f850: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
f860: 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e  memory,.** the n
f870: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
f880: 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
f890: 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
f8a0: 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
f8b0: 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  size..** ^If the
f8c0: 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
f8d0: 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
f8e0: 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
f8f0: 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
f900: 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
f910: 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
f920: 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
f930: 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
f940: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
f950: 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
f960: 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
f970: 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
f980: 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20  G_MALLOC].  ^If 
f990: 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
f9a0: 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
f9b0: 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51  L and either [SQ
f9c0: 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
f9d0: 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  YS3] or.** [SQLI
f9e0: 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
f9f0: 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20  5] are defined, 
fa00: 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61  then the alterna
fa10: 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tive memory.** a
fa20: 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61  llocator is enga
fa30: 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c  ged to handle al
fa40: 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d  l of SQLites mem
fa50: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
fa60: 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eeds..** The fir
fa70: 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
fa80: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
fa90: 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
faa0: 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
fab0: 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
fac0: 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
fad0: 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  of SQLite will b
fae0: 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
faf0: 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
fb00: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c  TE_CONFIG_MUTEX<
fb10: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
fb20: 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
fb30: 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
fb40: 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
fb50: 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69  inter to an.** i
fb60: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b  nstance of the [
fb70: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
fb80: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
fb90: 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  .  The argument 
fba0: 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74  specifies.** alt
fbb0: 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76  ernative low-lev
fbc0: 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  el mutex routine
fbd0: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
fbe0: 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74  place.** the mut
fbf0: 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  ex routines buil
fc00: 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
fc10: 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20    ^SQLite makes 
fc20: 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
fc30: 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
fc40: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
fc50: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
fc60: 65 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c  e before the cal
fc70: 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
fc80: 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72  _config()] retur
fc90: 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69  ns. ^If SQLite i
fca0: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
fcb0: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
fcc0: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
fcd0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
fce0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
fcf0: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
fd00: 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
fd10: 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
fd20: 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
fd30: 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
fd40: 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
fd50: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
fd60: 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
fd70: 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69  NFIG_MUTEX confi
fd80: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
fd90: 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
fda0: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
fdb0: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
fdc0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
fdd0: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
fde0: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
fdf0: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
fe00: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
fe10: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
fe20: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
fe30: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
fe40: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
fe50: 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
fe60: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
fe70: 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
fe80: 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
fe90: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
fea0: 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
feb0: 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
fec0: 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
fed0: 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
fee0: 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
fef0: 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
ff00: 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
ff10: 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
ff20: 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
ff30: 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
ff40: 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
ff50: 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
ff60: 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
ff70: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
ff80: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
ff90: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
ffa0: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
ffb0: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
ffc0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
ffd0: 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
ffe0: 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
fff0: 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
10000 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
10010 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
10020 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
10030 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
10040 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
10050 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
10060 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
10070 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
10080 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
10090 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
100a0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
100b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
100c0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
100d0 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20  s two arguments 
100e0 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74  that determine t
100f0 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65  he default.** me
10100 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10110 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  for the lookasid
10120 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
10130 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64  or on each.** [d
10140 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10150 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  on].  The first 
10160 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
10170 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
10180 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
10190 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65   slot and the se
101a0 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62  cond is the numb
101b0 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61  er of.** slots a
101c0 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68  llocated to each
101d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
101e0 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20  tion.)^  ^(This 
101f0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
10200 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69  ** <i>default</i
10210 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65  > lookaside size
10220 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42  . The [SQLITE_DB
10230 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
10240 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71  ].** verb to [sq
10250 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
10260 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  )] can be used t
10270 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f  o change the loo
10280 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67  kaside.** config
10290 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76  uration on indiv
102a0 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e  idual connection
102b0 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s.)^ </dd>.**.**
102c0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
102d0 49 47 5f 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  IG_PCACHE</dt>.*
102e0 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
102f0 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
10300 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
10310 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
10320 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65  to.** an [sqlite
10330 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
10340 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
10350 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
10360 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
10370 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
10380 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
10390 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c  ntation.)^  ^SQL
103a0 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
103b0 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
103c0 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
103d0 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
103e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
103f0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
10400 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
10410 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  TPCACHE</dt>.** 
10420 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
10430 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
10440 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
10450 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
10460 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
10470 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20  pcache_methods] 
10480 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20  object.  SQLite 
10490 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75  copies of the cu
104a0 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61  rrent.** page ca
104b0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
104c0 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a  on into that obj
104d0 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ect.)^ </dd>.**.
104e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
104f0 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
10500 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
10510 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
10520 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
10530 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74  guments: a point
10540 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74  er to a.** funct
10550 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20  ion with a call 
10560 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69  signature of voi
10570 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  d(*)(void*,int,c
10580 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a  onst char*), .**
10590 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74   and a pointer t
105a0 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20  o void. ^If the 
105b0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
105c0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74   is not NULL, it
105d0 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62   is.** invoked b
105e0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  y [sqlite3_log()
105f0 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63  ] to process eac
10600 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e  h logging event.
10610 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e    ^If the.** fun
10620 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
10630 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69   NULL, the [sqli
10640 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72  te3_log()] inter
10650 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e  face becomes a n
10660 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f  o-op..** ^The vo
10670 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  id pointer that 
10680 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
10690 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45  gument to SQLITE
106a0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a  _CONFIG_LOG is.*
106b0 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  * passed through
106c0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
106d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
106e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
106f0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
10700 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74  ction whenever t
10710 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  hat function is 
10720 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73  invoked.  ^The s
10730 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
10740 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72  to.** the logger
10750 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63   function is a c
10760 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74  opy of the first
10770 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
10780 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
10790 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  ** [sqlite3_log(
107a0 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69  )] call and is i
107b0 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20  ntended to be a 
107c0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
107d0 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   an.** [extended
107e0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20   result code].  
107f0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
10800 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  eter passed to t
10810 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20  he logger is.** 
10820 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65  log message afte
10830 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61  r formatting via
10840 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
10850 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51  tf()]..** The SQ
10860 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74  Lite logging int
10870 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
10880 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67  entrant; the log
10890 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ger function.** 
108a0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
108b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
108c0 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20   not invoke any 
108d0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
108e0 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d  ..** In a multi-
108f0 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
10900 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63  tion, the applic
10910 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
10920 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
10930 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
10940 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  afe. </dd>.**.**
10950 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
10960 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10970 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
10980 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
10990 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
109a0 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
109b0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
109c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
109d0 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
109e0 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
109f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
10a00 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
10a10 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
10a20 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
10a30 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10a40 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
10a50 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
10a60 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
10a70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10a80 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
10a90 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
10aa0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
10ab0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
10ac0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
10ad0 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
10ae0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
10af0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
10b00 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
10b10 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
10b20 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
10b30 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
10b40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10b50 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
10b60 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
10b70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10b80 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
10b90 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
10ba0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
10bb0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
10bc0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
10bd0 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
10be0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
10bf0 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
10c00 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
10c10 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
10c20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
10c30 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
10c40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
10c50 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
10c60 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
10c70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10c80 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
10c90 20 20 20 20 31 34 20 20 2f 2a 20 73 71 6c 69 74      14  /* sqlit
10ca0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
10cb0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
10cc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
10cd0 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20  CACHE    15  /* 
10ce0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
10cf0 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
10d00 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
10d10 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36  _LOG          16
10d20 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64    /* xFunc, void
10d30 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  * */../*.** CAPI
10d40 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
10d50 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
10d60 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
10d70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
10d80 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
10d90 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
10da0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10db0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
10dc0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
10dd0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10de0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
10df0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
10e00 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
10e10 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
10e20 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
10e30 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
10e40 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
10e50 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
10e60 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
10e70 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
10e80 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
10e90 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
10ea0 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
10eb0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
10ec0 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
10ed0 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
10ee0 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
10ef0 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
10f00 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
10f10 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
10f20 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
10f30 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
10f40 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
10f50 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
10f60 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
10f70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10f80 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
10f90 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
10fa0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
10fb0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
10fc0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
10fd0 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
10fe0 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
10ff0 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
11000 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
11010 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
11020 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
11030 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
11040 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
11050 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
11060 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
11070 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
11080 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
11090 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
110a0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
110b0 61 6e 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  an memory buffer
110c0 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
110d0 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
110e0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
110f0 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
11100 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
11110 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
11120 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
11130 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
11140 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
11150 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
11160 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
11170 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
11180 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
11190 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
111a0 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
111b0 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
111c0 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
111d0 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
111e0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
111f0 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
11200 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
11210 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
11220 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
11230 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
11240 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
11250 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
11260 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
11270 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
11280 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
11290 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
112a0 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
112b0 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
112c0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
112d0 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
112e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
112f0 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
11300 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
11310 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
11320 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
11330 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c   smaller multipl
11340 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c  e of 8.  ^(The l
11350 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a  ookaside memory.
11360 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
11370 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
11380 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f  connection can o
11390 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77  nly be changed w
113a0 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e  hen that.** conn
113b0 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75  ection is not cu
113c0 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f  rrently using lo
113d0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20  okaside memory, 
113e0 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  or in other word
113f0 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63  s.** when the "c
11400 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65  urrent value" re
11410 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
11420 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d  lite3_db_status]
11430 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  (D,[SQLITE_CONFI
11440 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e  G_LOOKASIDE],...
11450 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e  ) is zero..** An
11460 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61  y attempt to cha
11470 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
11480 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75  e memory configu
11490 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b  ration when look
114a0 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  aside.** memory 
114b0 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73  is in use leaves
114c0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
114d0 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64  on unchanged and
114e0 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
114f0 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64  LITE_BUSY].)^</d
11500 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  d>.**.** </dl>.*
11510 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
11520 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
11530 49 44 45 20 20 20 20 31 30 30 31 20 20 2f 2a 20  IDE    1001  /* 
11540 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  void* int int */
11550 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
11560 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
11570 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
11580 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
11590 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
115a0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
115b0 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
115c0 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
115d0 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
115e0 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
115f0 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
11600 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
11610 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
11620 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
11630 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
11640 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
11650 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54  bility..*/.SQLIT
11660 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
11670 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
11680 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
11690 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
116a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
116b0 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
116c0 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
116d0 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
116e0 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
116f0 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
11700 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
11710 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
11720 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
11730 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
11740 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
11750 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
11760 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
11770 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
11780 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
11790 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
117a0 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
117b0 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
117c0 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
117d0 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
117e0 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
117f0 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
11800 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
11810 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
11820 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
11830 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
11840 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
11850 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
11860 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
11870 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
11880 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
11890 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
118a0 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
118b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
118c0 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
118d0 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
118e0 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
118f0 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61   [INSERT]s.** ha
11900 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
11910 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
11920 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
11930 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
11940 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
11950 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
11960 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
11970 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  then the [rowid]
11980 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
11990 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72  .** row is retur
119a0 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
119b0 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
119c0 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75  he trigger is ru
119d0 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
119e0 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74  ce the trigger t
119f0 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76  erminates, the v
11a00 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
11a10 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
11a20 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20   reverts to the 
11a30 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72  last value inser
11a40 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74  ted before the t
11a50 72 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e 0a  rigger fired.)^.
11a60 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
11a70 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
11a80 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
11a90 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
11aa0 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
11ab0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
11ac0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
11ad0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
11ae0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
11af0 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
11b00 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
11b10 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
11b20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
11b30 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
11b40 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
11b50 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
11b60 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
11b70 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
11b80 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
11b90 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
11ba0 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
11bb0 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
11bc0 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
11bd0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
11be0 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
11bf0 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
11c00 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
11c10 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
11c20 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
11c30 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
11c40 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
11c50 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
11c60 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
11c70 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
11c80 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
11c90 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
11ca0 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
11cb0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
11cc0 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
11cd0 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
11ce0 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
11cf0 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
11d00 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
11d10 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
11d20 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
11d30 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
11d40 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
11d50 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
11d60 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
11d70 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
11d80 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
11d90 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
11da0 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
11db0 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
11dc0 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
11dd0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
11de0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
11df0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
11e00 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
11e10 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
11e20 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
11e30 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
11e40 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
11e50 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
11e60 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
11e70 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
11e80 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
11e90 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
11ea0 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
11eb0 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
11ec0 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
11ed0 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49  [rowid]..*/.SQLI
11ee0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
11ef0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
11f00 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
11f10 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
11f20 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
11f30 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
11f40 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
11f50 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
11f60 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
11f70 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
11f80 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
11f90 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
11fa0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
11fb0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
11fc0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
11fd0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
11fe0 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
11ff0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
12000 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
12010 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
12020 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
12030 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
12040 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
12050 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
12060 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
12070 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
12080 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
12090 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
120a0 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
120b0 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
120c0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
120d0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
120e0 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
120f0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
12100 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
12110 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
12120 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
12130 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
12140 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
12150 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
12160 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
12170 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
12180 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
12190 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
121a0 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
121b0 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
121c0 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
121d0 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
121e0 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
121f0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
12200 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
12210 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
12220 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
12230 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
12240 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
12250 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
12260 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
12270 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
12280 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
12290 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
122a0 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
122b0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
122c0 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
122d0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
122e0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
122f0 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
12300 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
12310 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
12320 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
12330 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
12340 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
12350 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
12360 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
12370 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
12380 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
12390 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
123a0 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
123b0 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
123c0 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
123d0 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
123e0 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
123f0 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
12400 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
12410 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
12420 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
12430 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
12440 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
12450 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
12460 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
12470 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
12480 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
12490 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
124a0 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
124b0 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
124c0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
124d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
124e0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
124f0 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
12500 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
12510 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
12520 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
12530 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
12540 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
12550 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
12560 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
12570 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
12580 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
12590 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
125a0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
125b0 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
125c0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
125d0 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
125e0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
125f0 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
12600 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
12610 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
12620 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
12630 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
12640 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
12650 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
12660 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
12670 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
12680 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
12690 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
126a0 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
126b0 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
126c0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
126d0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
126e0 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
126f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
12700 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
12710 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
12720 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
12730 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
12740 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
12750 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
12760 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
12770 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
12780 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
12790 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
127a0 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
127b0 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
127c0 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
127d0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
127e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
127f0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
12800 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
12810 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
12820 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
12830 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
12840 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
12850 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
12860 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
12870 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
12880 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12890 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
128a0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
128b0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
128c0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
128d0 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
128e0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
128f0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
12900 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
12910 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
12920 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
12930 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
12940 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
12950 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
12960 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
12970 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
12980 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
12990 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d  used by [INSERT]
129a0 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72  ,.** [UPDATE] or
129b0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
129c0 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
129d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
129e0 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
129f0 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20  .** ^(The count 
12a00 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
12a10 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
12a20 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  s() includes all
12a30 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d   changes.** from
12a40 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49   all [CREATE TRI
12a50 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20  GGER | trigger] 
12a60 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61  contexts and cha
12a70 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20  nges made by.** 
12a80 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
12a90 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a  ions]. However,.
12aa0 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
12ab0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
12ac0 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
12ad0 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45  plement [REPLACE
12ae0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  ] constraints,.*
12af0 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
12b00 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
12b10 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42  ng, or [DROP TAB
12b20 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20  LE] processing. 
12b30 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f   The.** count do
12b40 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72  es not include r
12b50 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61  ows of views tha
12b60 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45  t fire an [INSTE
12b70 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a  AD OF trigger],.
12b80 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65  ** though if the
12b90 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
12ba0 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ger makes change
12bb0 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68  s of its own, th
12bc0 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20  ose changes .** 
12bd0 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a  are counted.)^.*
12be0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
12bf0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66  otal_changes() f
12c00 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74  unction counts t
12c10 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f  he changes as so
12c20 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61  on as.** the sta
12c30 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
12c40 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
12c50 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
12c60 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a  atement handle.*
12c70 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  * is passed to [
12c80 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
12c90 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
12ca0 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
12cb0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
12cc0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
12cd0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
12ce0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
12cf0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
12d00 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67  the [total_chang
12d10 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
12d20 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
12d30 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
12d40 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
12d50 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
12d60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
12d70 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
12d80 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
12d90 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
12da0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
12db0 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
12dc0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
12dd0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
12de0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
12df0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
12e00 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
12e10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
12e20 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
12e30 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
12e40 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
12e50 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
12e60 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
12e70 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
12e80 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
12e90 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
12ea0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
12eb0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
12ec0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
12ed0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
12ee0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
12ef0 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
12f00 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
12f10 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
12f20 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
12f30 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
12f40 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
12f50 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
12f60 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
12f70 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
12f80 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
12f90 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
12fa0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
12fb0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
12fc0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
12fd0 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
12fe0 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
12ff0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
13000 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
13010 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13020 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
13030 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
13040 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
13050 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
13060 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
13070 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
13080 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
13090 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
130a0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
130b0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
130c0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
130d0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
130e0 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
130f0 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
13100 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
13110 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
13120 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
13130 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
13140 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
13150 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
13160 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
13170 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
13180 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
13190 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
131a0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
131b0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
131c0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
131d0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
131e0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
131f0 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
13200 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
13210 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
13220 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
13230 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
13240 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
13250 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
13260 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
13270 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
13280 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
13290 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
132a0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
132b0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
132c0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
132d0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
132e0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
132f0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
13300 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
13310 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
13320 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
13330 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
13340 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
13350 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
13360 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
13370 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
13380 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
13390 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
133a0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
133b0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
133c0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
133d0 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
133e0 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
133f0 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
13400 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
13410 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
13420 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
13430 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
13440 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
13450 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
13460 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
13470 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
13480 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
13490 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
134a0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
134b0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
134c0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
134d0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
134e0 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
134f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
13500 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
13510 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
13520 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
13530 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
13540 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
13550 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
13560 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
13570 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
13580 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13590 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
135a0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
135b0 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
135c0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
135d0 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
135e0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
135f0 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
13600 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
13610 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
13620 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
13630 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
13640 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
13650 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
13660 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
13670 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
13680 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
13690 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
136a0 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
136b0 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
136c0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
136d0 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
136e0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
136f0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
13700 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
13710 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
13720 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
13730 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
13740 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
13750 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
13760 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
13770 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
13780 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
13790 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
137a0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
137b0 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
137c0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
137d0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
137e0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
137f0 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
13800 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
13810 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
13820 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
13830 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
13840 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
13850 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
13860 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
13870 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
13880 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
13890 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
138a0 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
138b0 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
138c0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
138d0 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
138e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
138f0 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
13900 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
13910 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
13920 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
13930 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
13940 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
13950 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
13960 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
13970 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
13980 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
13990 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
139a0 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
139b0 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
139c0 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
139d0 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
139e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
139f0 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
13a00 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
13a10 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
13a20 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
13a30 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
13a40 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
13a50 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
13a60 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
13a70 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
13a80 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
13a90 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
13aa0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
13ab0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
13ac0 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
13ad0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
13ae0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
13af0 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
13b00 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
13b10 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
13b20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
13b30 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
13b40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
13b50 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
13b60 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
13b70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
13b80 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
13b90 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
13ba0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
13bb0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
13bc0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51  yte order..*/.SQ
13bd0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
13be0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
13bf0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
13c00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
13c10 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
13c20 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
13c30 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
13c40 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
13c50 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
13c60 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
13c70 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
13c80 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
13c90 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
13ca0 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
13cb0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
13cc0 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
13cd0 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
13ce0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
13cf0 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
13d00 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
13d10 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
13d20 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
13d30 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
13d40 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
13d50 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
13d60 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
13d70 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
13d80 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
13d90 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
13da0 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
13db0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
13dc0 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
13dd0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
13de0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
13df0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
13e00 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
13e10 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13e20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
13e30 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
13e40 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
13e50 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
13e60 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
13e70 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
13e80 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
13e90 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
13ea0 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
13eb0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
13ec0 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
13ed0 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
13ee0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
13ef0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
13f00 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
13f10 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
13f20 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
13f30 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
13f40 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
13f50 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
13f60 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
13f70 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
13f80 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
13f90 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
13fa0 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
13fb0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
13fc0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
13fd0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
13fe0 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
13ff0 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
14000 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
14010 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
14020 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
14030 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
14040 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
14050 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
14060 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
14070 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
14080 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
14090 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
140a0 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
140b0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
140c0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
140d0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
140e0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
140f0 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
14100 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
14110 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
14120 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
14130 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
14140 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
14150 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
14160 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
14170 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
14180 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
14190 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
141a0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
141b0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
141c0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
141d0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
141e0 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
141f0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
14200 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
14210 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
14220 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
14230 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
14240 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
14250 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
14260 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
14270 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
14280 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
14290 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
142a0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
142b0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
142c0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
142d0 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
142e0 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
142f0 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
14300 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
14310 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
14320 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
14330 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
14340 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
14350 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
14360 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
14370 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
14380 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
14390 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
143a0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
143b0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
143c0 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
143d0 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
143e0 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
143f0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
14400 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
14410 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
14420 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
14430 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
14440 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
14450 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
14460 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
14470 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
14480 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
14490 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
144a0 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
144b0 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
144c0 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
144d0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
144e0 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
144f0 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
14500 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
14510 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
14520 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
14530 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
14540 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
14550 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
14560 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
14570 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
14580 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
14590 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
145a0 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
145b0 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
145c0 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
145d0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
145e0 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
145f0 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
14600 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
14610 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
14620 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
14630 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
14640 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
14650 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
14660 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
14670 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
14680 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
14690 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
146a0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
146b0 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
146c0 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
146d0 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
146e0 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
146f0 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
14700 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
14710 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
14720 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
14730 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
14740 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
14750 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
14760 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
14770 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
14780 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
14790 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
147a0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
147b0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
147c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
147d0 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
147e0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
147f0 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
14800 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
14810 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
14820 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
14830 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
14840 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
14850 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
14860 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
14870 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
14880 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
14890 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
148a0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
148b0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
148c0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
148d0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
148e0 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
148f0 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
14900 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
14910 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
14920 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
14930 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
14940 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
14950 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
14960 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
14970 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
14980 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
14990 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
149a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
149b0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
149c0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
149d0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
149e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
149f0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
14a00 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
14a10 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
14a20 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
14a30 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
14a40 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
14a50 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
14a60 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
14a70 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
14a80 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
14a90 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
14aa0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
14ab0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
14ac0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
14ad0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
14ae0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
14af0 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
14b00 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
14b10 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
14b20 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
14b30 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
14b40 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
14b50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
14b60 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
14b70 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
14b80 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
14b90 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
14ba0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
14bb0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
14bc0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
14bd0 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
14be0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
14bf0 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
14c00 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
14c10 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
14c20 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
14c30 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
14c40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14c50 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
14c60 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
14c70 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
14c80 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
14c90 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
14ca0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
14cb0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
14cc0 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
14cd0 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
14ce0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
14cf0 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
14d00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
14d10 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
14d20 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
14d30 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
14d40 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
14d50 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
14d60 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
14d70 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
14d80 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
14d90 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
14da0 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
14db0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
14dc0 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
14dd0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
14de0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
14df0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
14e00 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
14e10 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
14e20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
14e30 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
14e40 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
14e50 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
14e60 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
14e70 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
14e80 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
14e90 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
14ea0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
14eb0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
14ec0 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
14ed0 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
14ee0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
14ef0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
14f00 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
14f10 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
14f20 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
14f30 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
14f40 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
14f50 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
14f60 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
14f70 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
14f80 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
14f90 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
14fa0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
14fb0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
14fc0 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
14fd0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
14fe0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
14ff0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
15000 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
15010 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
15020 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
15030 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
15040 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
15050 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
15060 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
15070 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
15080 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
15090 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
150a0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
150b0 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
150c0 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
150d0 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
150e0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
150f0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
15100 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
15110 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
15120 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
15130 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
15140 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
15150 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
15160 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
15170 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
15180 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
15190 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
151a0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
151b0 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
151c0 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
151d0 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
151e0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
151f0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
15200 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
15210 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
15220 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
15230 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
15240 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
15250 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
15260 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
15270 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
15280 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
15290 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
152a0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
152b0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
152c0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
152d0 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
152e0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
152f0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
15300 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
15310 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
15320 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
15330 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
15340 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
15350 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
15360 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
15370 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
15380 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
15390 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
153a0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
153b0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
153c0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
153d0 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
153e0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
153f0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
15400 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
15410 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
15420 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
15430 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
15440 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
15450 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
15460 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
15470 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
15480 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
15490 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
154a0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
154b0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
154c0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
154d0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
154e0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
154f0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
15500 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
15510 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
15520 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
15530 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
15540 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
15550 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
15560 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
15570 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
15580 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
15590 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
155a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
155b0 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
155c0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
155d0 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
155e0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
155f0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
15600 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
15610 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
15620 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
15630 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
15640 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
15650 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
15660 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
15670 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
15680 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
15690 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
156a0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
156b0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
156c0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
156d0 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
156e0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
156f0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
15700 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
15710 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
15720 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
15730 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
15740 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
15750 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
15760 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
15770 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
15780 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
15790 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
157a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
157b0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
157c0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
157d0 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
157e0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
157f0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
15800 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
15810 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
15820 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
15830 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
15840 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
15850 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
15860 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
15870 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
15880 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
15890 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
158a0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
158b0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
158c0 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
158d0 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
158e0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
158f0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
15900 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
15910 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
15920 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
15930 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
15940 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
15950 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
15960 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
15970 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
15980 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
15990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
159a0 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  sg()]..*/.SQLITE
159b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
159c0 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
159d0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
159e0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
159f0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
15a00 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
15a10 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
15a20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
15a30 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
15a40 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
15a50 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
15a60 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
15a70 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
15a80 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
15a90 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
15aa0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
15ab0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
15ac0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
15ad0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
15ae0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
15af0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
15b00 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
15b10 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c  n here */.);.SQL
15b20 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
15b30 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
15b40 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
15b50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
15b60 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
15b70 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
15b80 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
15b90 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
15ba0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
15bb0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
15bc0 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
15bd0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
15be0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
15bf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
15c00 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
15c10 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
15c20 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
15c30 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
15c40 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
15c50 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
15c60 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
15c70 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
15c80 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
15c90 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
15ca0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
15cb0 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
15cc0 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
15cd0 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
15ce0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
15cf0 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
15d00 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
15d10 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
15d20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
15d30 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
15d40 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
15d50 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
15d60 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
15d70 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
15d80 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
15d90 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
15da0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
15db0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
15dc0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
15dd0 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
15de0 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
15df0 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
15e00 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
15e10 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
15e20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
15e30 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
15e40 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
15e50 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
15e60 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
15e70 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
15e80 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
15e90 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
15ea0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
15eb0 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
15ec0 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
15ed0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
15ee0 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
15ef0 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
15f00 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
15f10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
15f20 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
15f30 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
15f40 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
15f50 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
15f60 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
15f70 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
15f80 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
15f90 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
15fa0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
15fb0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
15fc0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
15fd0 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
15fe0 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
15ff0 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
16000 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
16010 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
16020 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
16030 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
16040 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
16050 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
16060 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
16070 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
16080 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
16090 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
160a0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
160b0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
160c0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
160d0 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
160e0 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
160f0 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
16100 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
16110 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
16120 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
16130 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
16140 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
16150 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
16160 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
16170 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
16180 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
16190 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
161a0 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
161b0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
161c0 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
161d0 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
161e0 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
161f0 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
16200 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
16210 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
16220 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
16230 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
16240 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
16250 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
16260 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
16270 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
16280 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
16290 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
162a0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
162b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
162c0 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
162d0 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
162e0 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
162f0 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a  null-terminated.
16300 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
16310 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
16320 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
16330 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
16340 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
16350 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
16360 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
16370 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
16380 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
16390 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
163a0 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
163b0 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
163c0 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
163d0 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
163e0 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
163f0 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
16400 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
16410 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
16420 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
16430 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
16440 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
16450 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
16460 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
16470 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
16480 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
16490 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
164a0 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
164b0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
164c0 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
164d0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
164e0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
164f0 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
16500 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
16510 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
16520 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
16530 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
16540 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
16550 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
16560 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
16570 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
16580 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
16590 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
165a0 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
165b0 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
165c0 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
165d0 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
165e0 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
165f0 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
16600 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
16610 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
16620 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
16630 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
16640 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
16650 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
16660 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
16670 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
16680 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
16690 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
166a0 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
166b0 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
166c0 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
166d0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
166e0 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
166f0 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
16700 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
16710 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
16720 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
16730 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
16740 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
16750 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
16760 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
16770 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
16780 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
16790 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
167a0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
167b0 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
167c0 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
167d0 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
167e0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
167f0 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
16800 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
16810 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
16820 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
16830 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
16840 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
16850 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
16860 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
16870 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
16880 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
16890 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
168a0 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
168b0 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
168c0 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
168d0 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
168e0 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
168f0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
16900 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
16910 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
16920 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
16930 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
16940 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
16950 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
16960 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
16970 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
16980 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
16990 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
169a0 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
169b0 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
169c0 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
169d0 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
169e0 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
169f0 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
16a00 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
16a10 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
16a20 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
16a30 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
16a40 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
16a50 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
16a60 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
16a70 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
16a80 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
16a90 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
16aa0 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
16ab0 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
16ac0 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
16ad0 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c  string.)^.*/.SQL
16ae0 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
16af0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
16b00 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
16b10 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
16b20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
16b30 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
16b40 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f  a_list);.SQLITE_
16b50 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
16b60 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
16b70 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
16b80 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41  , ...);.SQLITE_A
16b90 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
16ba0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
16bb0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
16bc0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
16bd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
16be0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
16bf0 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
16c00 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
16c10 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
16c20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
16c30 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
16c40 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
16c50 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
16c60 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
16c70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
16c80 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
16c90 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
16ca0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
16cb0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
16cc0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
16cd0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
16ce0 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
16cf0 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
16d00 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
16d10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
16d20 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
16d30 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
16d40 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
16d50 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
16d60 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
16d70 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
16d80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
16d90 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
16da0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
16db0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
16dc0 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
16dd0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
16de0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
16df0 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
16e00 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
16e10 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
16e20 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
16e30 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
16e40 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
16e50 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
16e60 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
16e70 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
16e80 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
16e90 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
16ea0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
16eb0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
16ec0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
16ed0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
16ee0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
16ef0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
16f00 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
16f10 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
16f20 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
16f30 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
16f40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
16f50 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
16f60 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
16f70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
16f80 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
16f90 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
16fa0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
16fb0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
16fc0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
16fd0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
16fe0 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
16ff0 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
17000 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
17010 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
17020 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
17030 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
17040 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
17050 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
17060 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
17070 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
17080 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
17090 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
170a0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
170b0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
170c0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
170d0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
170e0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
170f0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
17100 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
17110 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
17120 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
17130 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
17140 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
17150 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
17160 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
17170 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
17180 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
17190 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
171a0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
171b0 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
171c0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
171d0 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
171e0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
171f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17200 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
17210 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
17220 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
17230 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
17240 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
17250 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
17260 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
17270 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
17280 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
17290 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
172a0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
172b0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
172c0 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
172d0 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
172e0 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
172f0 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
17300 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
17310 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
17320 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
17330 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
17340 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
17350 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17360 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
17370 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
17380 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
17390 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
173a0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
173b0 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
173c0 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
173d0 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
173e0 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
173f0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
17400 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
17410 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
17420 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
17430 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
17440 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
17450 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
17460 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
17470 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
17480 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
17490 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
174a0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
174b0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
174c0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
174d0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
174e0 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
174f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
17500 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
17510 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17520 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
17530 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
17540 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
17550 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
17560 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
17570 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
17580 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
17590 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
175a0 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
175b0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
175c0 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
175d0 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
175e0 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
175f0 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
17600 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
17610 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
17620 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
17630 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
17640 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
17650 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
17660 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
17670 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
17680 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
17690 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
176a0 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
176b0 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
176c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
176d0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
176e0 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77  **.** The Window
176f0 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
17700 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68  ayer calls.** th
17710 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
17720 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
17730 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
17740 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
17750 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
17760 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
17770 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
17780 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
17790 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
177a0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
177b0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
177c0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
177d0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
177e0 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20  tion errors are 
177f0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
17800 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74   they are report
17810 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
17820 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
17830 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
17840 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
17850 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
17860 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
17870 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
17880 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
17890 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
178a0 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
178b0 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
178c0 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
178d0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
178e0 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
178f0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
17900 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
17910 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
17920 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
17930 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
17940 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
17950 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
17960 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
17970 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
17980 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
17990 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
179a0 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
179b0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
179c0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
179d0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
179e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
179f0 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
17a00 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  (int);.SQLITE_AP
17a10 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
17a20 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
17a30 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
17a40 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
17a50 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
17a60 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
17a70 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
17a80 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
17a90 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
17aa0 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
17ab0 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
17ac0 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
17ad0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
17ae0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
17af0 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
17b00 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
17b10 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
17b20 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
17b30 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
17b40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
17b50 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
17b60 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
17b70 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
17b80 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
17b90 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
17ba0 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
17bb0 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
17bc0 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
17bd0 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
17be0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
17bf0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
17c00 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
17c10 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
17c20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
17c30 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
17c40 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
17c50 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
17c60 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
17c70 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
17c80 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
17c90 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
17ca0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
17cb0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
17cc0 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
17cd0 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
17ce0 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
17cf0 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
17d00 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
17d10 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
17d20 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
17d30 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
17d40 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
17d50 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
17d60 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
17d70 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
17d80 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
17d90 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
17da0 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
17db0 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
17dc0 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
17dd0 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
17de0 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
17df0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
17e00 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
17e10 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
17e20 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
17e30 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
17e40 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
17e50 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
17e60 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
17e70 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
17e80 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
17e90 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
17ea0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
17eb0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
17ec0 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ed(void);.SQLITE
17ed0 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
17ee0 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
17ef0 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
17f00 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
17f10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
17f20 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
17f30 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
17f40 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
17f50 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
17f60 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
17f70 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
17f80 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
17f90 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
17fa0 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
17fb0 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
17fc0 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
17fd0 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
17fe0 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
17ff0 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
18000 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
18010 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
18020 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
18030 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
18040 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
18050 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
18060 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
18070 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
18080 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
18090 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
180a0 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
180b0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
180c0 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
180d0 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
180e0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
180f0 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
18100 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
18110 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
18120 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
18130 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
18140 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
18150 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
18160 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
18170 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
18180 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
18190 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
181a0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
181b0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
181c0 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20   object..** ^On 
181d0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
181e0 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20  nvocations, the 
181f0 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
18200 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
18210 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
18220 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
18230 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
18240 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
18250 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
18260 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
18270 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
18280 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
18290 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
182a0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
182b0 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
182c0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
182d0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
182e0 65 67 69 73 74 65 72 73 20 61 20 61 75 74 68 6f  egisters a autho
182f0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
18300 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
18310 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
18320 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
18330 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
18340 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
18350 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
18360 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
18370 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
18380 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
18390 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
183a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
183b0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
183c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
183d0 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
183e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
183f0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
18400 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
18410 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
18420 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
18430 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
18440 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
18450 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
18460 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
18470 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
18480 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
18490 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
184a0 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
184b0 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
184c0 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
184d0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
184e0 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
184f0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
18500 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
18510 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
18520 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
18530 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
18540 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
18550 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
18560 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
18570 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
18580 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
18590 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
185a0 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
185b0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
185c0 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
185d0 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
185e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
185f0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
18600 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
18610 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
18620 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
18630 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
18640 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
18650 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
18660 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
18670 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
18680 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
18690 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
186a0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
186b0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
186c0 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
186d0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
186e0 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
186f0 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
18700 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
18710 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
18720 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
18730 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
18740 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
18750 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
18760 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
18770 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
18780 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
18790 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
187a0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
187b0 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
187c0 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
187d0 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
187e0 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
187f0 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
18800 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
18810 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
18820 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
18830 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
18840 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
18850 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
18860 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18870 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
18880 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
18890 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
188a0 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
188b0 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
188c0 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
188d0 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
188e0 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
188f0 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
18900 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
18910 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
18920 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
18930 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
18940 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
18950 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
18960 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
18970 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
18980 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
18990 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
189a0 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
189b0 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
189c0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
189d0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
189e0 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
189f0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
18a00 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
18a10 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
18a20 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
18a30 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
18a40 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
18a50 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
18a60 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
18a70 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
18a80 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
18a90 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
18aa0 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
18ab0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
18ac0 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
18ad0 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
18ae0 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
18af0 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
18b00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
18b10 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
18b20 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
18b30 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
18b40 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
18b50 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
18b60 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
18b70 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
18b80 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
18b90 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
18ba0 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
18bb0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
18bc0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
18bd0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
18be0 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
18bf0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
18c00 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
18c10 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
18c20 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
18c30 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
18c40 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
18c50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
18c60 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
18c70 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
18c80 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
18c90 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
18ca0 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
18cb0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
18cc0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
18cd0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
18ce0 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
18cf0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
18d00 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
18d10 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
18d20 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
18d30 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
18d40 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
18d50 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
18d60 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
18d70 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
18d80 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
18d90 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
18da0 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
18db0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
18dc0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
18dd0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
18de0 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
18df0 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
18e00 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
18e10 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
18e20 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
18e30 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
18e40 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
18e50 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
18e60 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
18e70 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
18e80 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
18e90 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
18ea0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
18eb0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
18ec0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
18ed0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
18ee0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
18ef0 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
18f00 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
18f10 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
18f20 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
18f30 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
18f40 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
18f50 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
18f60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
18f70 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
18f80 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
18f90 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
18fa0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
18fb0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
18fc0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
18fd0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
18fe0 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
18ff0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
19000 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
19010 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
19020 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
19030 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
19040 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
19050 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
19060 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
19070 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19080 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
19090 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
190a0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
190b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
190c0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
190d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
190e0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
190f0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
19100 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
19110 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19120 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
19130 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
19140 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
19150 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
19160 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
19170 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
19180 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
19190 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
191a0 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
191b0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
191c0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
191d0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
191e0 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
191f0 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
19200 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
19210 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
19220 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
19230 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
19240 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
19250 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19260 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
19270 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
19280 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19290 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
192a0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
192b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
192c0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
192d0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
192e0 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
192f0 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
19300 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
19310 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
19320 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
19330 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
19340 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
19350 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
19360 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
19370 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
19380 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
19390 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
193a0 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
193b0 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
193c0 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
193d0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
193e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
193f0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
19400 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
19410 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
19420 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
19430 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
19440 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
19450 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
19460 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
19470 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19480 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
19490 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
194a0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
194b0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
194c0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
194d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
194e0 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
194f0 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
19500 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
19510 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
19520 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
19530 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
19540 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
19550 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
19560 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
19570 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
19580 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
19590 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
195a0 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
195b0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
195c0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
195d0 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f  ITE_DENY   1   /
195e0 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20  * Abort the SQL 
195f0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61  statement with a
19600 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  n error */.#defi
19610 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  ne SQLITE_IGNORE
19620 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c   2   /* Don't al
19630 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20  low access, but 
19640 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61  don't generate a
19650 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a  n error */../*.*
19660 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
19670 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f  orizer Action Co
19680 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
19690 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
196a0 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61  rizer()] interfa
196b0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
196c0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
196d0 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f  .** that is invo
196e0 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65  ked to authorize
196f0 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61   certain SQL sta
19700 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20  tement actions. 
19710 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
19720 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
19730 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
19740 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74  nteger code that
19750 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68   specifies.** wh
19760 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69  at action is bei
19770 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ng authorized.  
19780 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e  These are the in
19790 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64  teger action cod
197a0 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61  es that.** the a
197b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
197c0 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64  ck may be passed
197d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63  ..**.** These ac
197e0 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73  tion code values
197f0 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69   signify what ki
19800 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20  nd of operation 
19810 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68  is to be.** auth
19820 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64  orized.  The 3rd
19830 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74   and 4th paramet
19840 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ers to the autho
19850 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  rization.** call
19860 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69  back function wi
19870 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73  ll be parameters
19880 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69   or NULL dependi
19890 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74  ng on which of t
198a0 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73  hese.** codes is
198b0 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63   used as the sec
198c0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
198d0 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65  ^(The 5th parame
198e0 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75  ter to the.** au
198f0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
19900 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  k is the name of
19910 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22   the database ("
19920 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a  main", "temp",.*
19930 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69  * etc.) if appli
19940 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36  cable.)^  ^The 6
19950 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
19960 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
19970 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68  allback.** is th
19980 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e  e name of the in
19990 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72  ner-most trigger
199a0 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73   or view that is
199b0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
199c0 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61  .** the access a
199d0 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69  ttempt or NULL i
199e0 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74  f this access at
199f0 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c  tempt is directl
19a00 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65  y from.** top-le
19a10 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f  vel SQL code..*/
19a20 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
19a30 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
19a40 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72  ************* 3r
19a50 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34  d ************ 4
19a60 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a  th ***********/.
19a70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
19a80 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20  REATE_INDEX     
19a90 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65       1   /* Inde
19aa0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
19ab0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
19ac0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
19ad0 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20  EATE_TABLE      
19ae0 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65      2   /* Table
19af0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
19b00 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
19b10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
19b20 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20  ATE_TEMP_INDEX  
19b30 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20     3   /* Index 
19b40 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
19b50 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
19b60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
19b70 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20  TE_TEMP_TABLE   
19b80 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    4   /* Table N
19b90 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
19ba0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
19bb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
19bc0 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20  E_TEMP_TRIGGER  
19bd0 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20   5   /* Trigger 
19be0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
19bf0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
19c00 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
19c10 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20  _TEMP_VIEW      
19c20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  6   /* View Name
19c30 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
19c40 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
19c50 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
19c60 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37  TRIGGER        7
19c70 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
19c80 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
19c90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
19ca0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56   SQLITE_CREATE_V
19cb0 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20  IEW           8 
19cc0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
19cd0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
19ce0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
19cf0 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20  SQLITE_DELETE   
19d00 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20               9  
19d10 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
19d20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
19d30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
19d40 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58  QLITE_DROP_INDEX
19d50 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20             10   
19d60 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
19d70 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
19d80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
19d90 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20  LITE_DROP_TABLE 
19da0 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f            11   /
19db0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
19dc0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
19dd0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
19de0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e  ITE_DROP_TEMP_IN
19df0 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a  DEX      12   /*
19e00 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
19e10 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
19e20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19e30 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42  TE_DROP_TEMP_TAB
19e40 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20  LE      13   /* 
19e50 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
19e60 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
19e70 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
19e80 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47  E_DROP_TEMP_TRIG
19e90 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54  GER    14   /* T
19ea0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
19eb0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
19ec0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19ed0 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20  _DROP_TEMP_VIEW 
19ee0 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69        15   /* Vi
19ef0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
19f00 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
19f10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19f20 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20  DROP_TRIGGER    
19f30 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69       16   /* Tri
19f40 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
19f50 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
19f60 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19f70 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20  ROP_VIEW        
19f80 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77      17   /* View
19f90 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
19fa0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
19fb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
19fc0 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20  SERT            
19fd0 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65     18   /* Table
19fe0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
19ff0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1a000 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41  efine SQLITE_PRA
1a010 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
1a020 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61    19   /* Pragma
1a030 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72   Name     1st ar
1a040 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65  g or NULL */.#de
1a050 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
1a060 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1a070 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   20   /* Table N
1a080 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
1a090 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
1a0a0 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43  ine SQLITE_SELEC
1a0b0 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
1a0c0 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  21   /* NULL    
1a0d0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1a0e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1a0f0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41  ne SQLITE_TRANSA
1a100 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32  CTION          2
1a110 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e  2   /* Operation
1a120 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1a130 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1a140 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20  e SQLITE_UPDATE 
1a150 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33                23
1a160 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1a170 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
1a180 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1a190 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20   SQLITE_ATTACH  
1a1a0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20               24 
1a1b0 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20    /* Filename   
1a1c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1a1d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1a1e0 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20  SQLITE_DETACH   
1a1f0 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20              25  
1a200 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1a210 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20  e   NULL        
1a220 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1a230 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c  QLITE_ALTER_TABL
1a240 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20  E          26   
1a250 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1a260 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1a270 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a280 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20  LITE_REINDEX    
1a290 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f            27   /
1a2a0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1a2b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1a2c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a2d0 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20  ITE_ANALYZE     
1a2e0 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a           28   /*
1a2f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1a300 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1a310 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a320 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45  TE_CREATE_VTABLE
1a330 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20          29   /* 
1a340 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1a350 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1a360 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a370 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20  E_DROP_VTABLE   
1a380 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54         30   /* T
1a390 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1a3a0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1a3b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a3c0 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20  _FUNCTION       
1a3d0 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55        31   /* NU
1a3e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75  LL            Fu
1a3f0 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f  nction Name   */
1a400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a410 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20  SAVEPOINT       
1a420 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65       32   /* Ope
1a430 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76  ration       Sav
1a440 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a  epoint Name  */.
1a450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1a460 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20  OPY             
1a470 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c       0   /* No l
1a480 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f  onger used */../
1a490 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1a4a0 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
1a4b0 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
1a4c0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1a4d0 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
1a4e0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
1a4f0 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
1a500 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
1a510 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
1a520 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
1a530 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1a540 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1a550 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1a560 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1a570 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
1a580 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
1a590 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
1a5a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1a5b0 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
1a5c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1a5d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1a5e0 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1a5f0 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
1a600 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
1a610 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
1a620 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
1a630 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
1a640 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
1a650 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
1a660 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
1a670 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1a680 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
1a690 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
1a6a0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
1a6b0 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
1a6c0 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
1a6d0 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
1a6e0 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
1a6f0 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
1a700 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
1a710 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er.)^.**.** ^The
1a720 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1a730 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1a740 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
1a750 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
1a760 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74 61   as each SQL sta
1a770 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e  tement finishes.
1a780 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
1a790 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73  allback contains
1a7a0 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  .** the original
1a7b0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1a7c0 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20  and an estimate 
1a7d0 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69  of wall-clock ti
1a7e0 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e  me.** of how lon
1a7f0 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  g that statement
1a800 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e   took to run.  ^
1a810 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
1a820 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20  back.** time is 
1a830 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f  in units of nano
1a840 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72  seconds, however
1a850 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
1a860 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
1a870 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f  s only capable o
1a880 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65  f millisecond re
1a890 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20  solution so the 
1a8a0 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66  six least signif
1a8b0 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20  icant.** digits 
1a8c0 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65 20  in the time are 
1a8d0 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75  meaningless.  Fu
1a8e0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1a8f0 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74   SQLite.** might
1a900 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65 72   provide greater
1a910 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74   resolution on t
1a920 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c  he profiler call
1a930 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71  back.  The.** sq
1a940 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
1a950 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73  function is cons
1a960 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e  idered experimen
1a970 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75  tal and is.** su
1a980 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
1a990 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  in future versio
1a9a0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ns of SQLite..*/
1a9b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1a9c0 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28   *sqlite3_trace(
1a9d0 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a  sqlite3*, void(*
1a9e0 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f  xTrace)(void*,co
1a9f0 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64  nst char*), void
1aa00 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
1aa10 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54  QLITE_EXPERIMENT
1aa20 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  AL void *sqlite3
1aa30 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33  _profile(sqlite3
1aa40 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f  *,.   void(*xPro
1aa50 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  file)(void*,cons
1aa60 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f  t char*,sqlite3_
1aa70 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b  uint64), void*);
1aa80 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1aa90 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73 73  : Query Progress
1aaa0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1aab0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72   ^The sqlite3_pr
1aac0 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44  ogress_handler(D
1aad0 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63  ,N,X,P) interfac
1aae0 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  e causes the cal
1aaf0 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f  lback.** functio
1ab00 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  n X to be invoke
1ab10 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64  d periodically d
1ab20 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69  uring long runni
1ab30 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b  ng calls to.** [
1ab40 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c  sqlite3_exec()],
1ab50 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1ab60 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67  ] and [sqlite3_g
1ab70 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a  et_table()] for.
1ab80 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
1ab90 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78  ection D.  An ex
1aba0 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68  ample use for th
1abb0 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  is.** interface 
1abc0 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49  is to keep a GUI
1abd0 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67 20   updated during 
1abe0 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a  a large query..*
1abf0 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65  *.** ^The parame
1ac00 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64 20  ter P is passed 
1ac10 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f  through as the o
1ac20 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
1ac30 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63   the .** callbac
1ac40 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e  k function X.  ^
1ac50 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  The parameter N 
1ac60 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
1ac70 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61   .** [virtual ma
1ac80 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f  chine instructio
1ac90 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61  ns] that are eva
1aca0 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73  luated between s
1acb0 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76  uccessive.** inv
1acc0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
1acd0 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a  callback X..**.*
1ace0 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  * ^Only a single
1acf0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1ad00 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64  r may be defined
1ad10 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72   at one time per
1ad20 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1ad30 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69  nnection]; setti
1ad40 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73  ng a new progres
1ad50 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c  s handler cancel
1ad60 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65  s the.** old one
1ad70 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61  .  ^Setting para
1ad80 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20  meter X to NULL 
1ad90 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f  disables the pro
1ada0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1adb0 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20  * ^The progress 
1adc0 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20  handler is also 
1add0 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74  disabled by sett
1ade0 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65  ing N to a value
1adf0 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e   less.** than 1.
1ae00 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70  .**.** ^If the p
1ae10 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b  rogress callback
1ae20 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
1ae30 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  o, the operation
1ae40 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74   is.** interrupt
1ae50 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72  ed.  This featur
1ae60 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
1ae70 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20   implement a.** 
1ae80 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20  "Cancel" button 
1ae90 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73  on a GUI progres
1aea0 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a  s dialog box..**
1aeb0 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73  .** The progress
1aec0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1aed0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1aee0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1aef0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1af00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1af10 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1af20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1af30 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68  dler..** Note th
1af40 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  at [sqlite3_prep
1af50 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
1af60 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62  qlite3_step()] b
1af70 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72  oth modify their
1af80 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1af90 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  nections for the
1afa0 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64   meaning of "mod
1afb0 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72  ify" in this par
1afc0 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51  agraph..**.*/.SQ
1afd0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
1afe0 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1aff0 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c  andler(sqlite3*,
1b000 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69   int, int(*)(voi
1b010 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  d*), void*);../*
1b020 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70  .** CAPI3REF: Op
1b030 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74 61  ening A New Data
1b040 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a  base Connection.
1b050 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
1b060 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53 51  tines open an SQ
1b070 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66 69  Lite database fi
1b080 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69 73  le whose name is
1b090 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a 2a   given by the.**
1b0a0 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1b0b0 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
1b0c0 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
1b0d0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
1b0e0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
1b0f0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
1b100 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
1b110 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
1b120 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
1b130 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
1b140 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
1b150 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
1b160 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
1b170 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
1b180 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
1b190 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
1b1a0 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
1b1b0 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
1b1c0 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
1b1d0 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
1b1e0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
1b1f0 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
1b200 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
1b210 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
1b220 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
1b230 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
1b240 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
1b250 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
1b260 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
1b270 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
1b280 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
1b290 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
1b2a0 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
1b2b0 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
1b2c0 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
1b2d0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
1b2e0 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
1b2f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
1b300 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
1b310 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
1b320 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
1b330 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
1b340 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
1b350 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
1b360 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
1b370 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
1b380 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
1b390 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
1b3a0 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
1b3b0 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
1b3c0 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
1b3d0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1b3e0 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
1b3f0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1b400 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1b410 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
1b420 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
1b430 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
1b440 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
1b450 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
1b460 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
1b470 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
1b480 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
1b490 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
1b4a0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
1b4b0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
1b4c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
1b4d0 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
1b4e0 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
1b4f0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
1b500 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
1b510 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
1b520 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
1b530 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
1b540 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
1b550 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
1b560 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
1b570 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
1b580 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
1b590 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
1b5a0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
1b5b0 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
1b5c0 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
1b5d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
1b5e0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
1b5f0 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
1b600 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
1b610 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
1b620 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
1b630 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
1b640 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
1b650 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
1b660 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
1b670 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1b680 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
1b690 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1b6a0 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ACHE],.** and/or
1b6b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
1b6c0 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
1b6d0 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
1b6e0 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1b6f0 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
1b700 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1b710 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1b720 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
1b730 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
1b740 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
1b750 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
1b760 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
1b770 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
1b780 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
1b790 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1b7a0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1b7b0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1b7c0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1b7d0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
1b7e0 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
1b7f0 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
1b800 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
1b810 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
1b820 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1b830 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
1b840 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
1b850 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
1b860 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
1b870 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
1b880 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
1b890 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
1b8a0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1b8b0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
1b8c0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
1b8d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1b8e0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1b8f0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1b900 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
1b910 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
1b920 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
1b930 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
1b940 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
1b950 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
1b960 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1b970 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1b980 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
1b990 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
1b9a0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
1b9b0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1b9c0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1b9d0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
1b9e0 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
1b9f0 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f 6e  hown above or on
1ba00 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e 61  e of the combina
1ba10 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76  tions shown abov
1ba20 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77 69  e combined.** wi
1ba30 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
1ba40 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
1ba50 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1ba60 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  UTEX],.** [SQLIT
1ba70 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1ba80 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  HE] and/or [SQLI
1ba90 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1baa0 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a 20  ACHE] flags,.** 
1bab0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1bac0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
1bad0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
1bae0 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1baf0 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
1bb00 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1bb10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1bb20 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
1bb30 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
1bb40 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
1bb50 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
1bb60 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
1bb70 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
1bb80 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
1bb90 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
1bba0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
1bbb0 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1bbc0 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1bbd0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1bbe0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
1bbf0 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
1bc00 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
1bc10 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
1bc20 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
1bc30 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
1bc40 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
1bc50 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
1bc60 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
1bc70 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
1bc80 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
1bc90 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
1bca0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1bcb0 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
1bcc0 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
1bcd0 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
1bce0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1bcf0 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
1bd00 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
1bd10 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
1bd20 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
1bd30 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
1bd40 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
1bd50 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
1bd60 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
1bd70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1bd80 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
1bd90 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
1bda0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1bdb0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
1bdc0 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  nabled..**.** ^I
1bdd0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
1bde0 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
1bdf0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1be00 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
1be10 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
1be20 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
1be30 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
1be40 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
1be50 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
1be60 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
1be70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1be80 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
1be90 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1bea0 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
1beb0 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
1bec0 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
1bed0 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
1bee0 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
1bef0 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
1bf00 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
1bf10 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
1bf20 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1bf30 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
1bf40 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
1bf50 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
1bf60 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
1bf70 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
1bf80 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
1bf90 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
1bfa0 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
1bfb0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
1bfc0 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
1bfd0 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
1bfe0 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
1bff0 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
1c000 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1c010 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
1c020 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
1c030 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
1c040 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
1c050 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
1c060 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1c070 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1c080 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
1c090 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
1c0a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c0b0 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  ) is the name of
1c0c0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1c0d0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68 61  _vfs] object tha
1c0e0 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f 70  t defines the op
1c0f0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
1c100 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a 2a  nterface that.**
1c110 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1c120 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f  e connection sho
1c130 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74 68  uld use.  ^If th
1c140 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
1c150 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20  er is.** a NULL 
1c160 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68 65  pointer then the
1c170 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
1c180 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69 73  3_vfs] object is
1c190 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e   used..**.** <b>
1c1a0 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20  Note to Windows 
1c1b0 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20  users:</b>  The 
1c1c0 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f  encoding used fo
1c1d0 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  r the filename a
1c1e0 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71  rgument.** of sq
1c1f0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
1c200 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1c210 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38  () must be UTF-8
1c220 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a  , not whatever.*
1c230 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63 75  * codepage is cu
1c240 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e  rrently defined.
1c250 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74    Filenames cont
1c260 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69  aining internati
1c270 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65  onal.** characte
1c280 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  rs must be conve
1c290 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72  rted to UTF-8 pr
1c2a0 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74  ior to passing t
1c2b0 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69  hem into.** sqli
1c2c0 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71  te3_open() or sq
1c2d0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
1c2e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1c2f0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  nt sqlite3_open(
1c300 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
1c310 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
1c320 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
1c330 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
1c340 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
1c350 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
1c360 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
1c370 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
1c380 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  nt sqlite3_open1
1c390 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  6(.  const void 
1c3a0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
1c3b0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
1c3c0 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20  e (UTF-16) */.  
1c3d0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1c3e0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1c3f0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1c400 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
1c410 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
1c420 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63  en_v2(.  const c
1c430 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  har *filename,  
1c440 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
1c450 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f  ename (UTF-8) */
1c460 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
1c470 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b,         /* OU
1c480 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
1c490 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61  dle */.  int fla
1c4a0 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  gs,             
1c4b0 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63   /* Flags */.  c
1c4c0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20  onst char *zVfs 
1c4d0 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
1c4e0 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20  f VFS module to 
1c4f0 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  use */.);../*.**
1c500 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72   CAPI3REF: Error
1c510 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61   Codes And Messa
1c520 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ges.**.** ^The s
1c530 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1c540 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
1c550 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b  ns the numeric [
1c560 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a  result code] or.
1c570 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1c580 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68  ult code] for th
1c590 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61  e most recent fa
1c5a0 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41  iled sqlite3_* A
1c5b0 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63  PI call.** assoc
1c5c0 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61  iated with a [da
1c5d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c5e0 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41  n]. If a prior A
1c5f0 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a  PI call failed.*
1c600 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72  * but the most r
1c610 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73  ecent API call s
1c620 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65  ucceeded, the re
1c630 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a  turn value from.
1c640 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  ** sqlite3_errco
1c650 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65  de() is undefine
1c660 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1c670 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
1c680 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
1c690 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63   is the same exc
1c6a0 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61  ept that it alwa
1c6b0 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a  ys returns the .
1c6c0 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
1c6d0 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77  ult code] even w
1c6e0 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73  hen extended res
1c6f0 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a  ult codes are.**
1c700 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
1c710 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72   ^The sqlite3_er
1c720 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74  rmsg() and sqlit
1c730 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65  e3_errmsg16() re
1c740 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e  turn English-lan
1c750 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68  guage.** text th
1c760 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65  at describes the
1c770 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65   error, as eithe
1c780 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31  r UTF-8 or UTF-1
1c790 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  6 respectively..
1c7a0 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68  ** ^(Memory to h
1c7b0 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65  old the error me
1c7c0 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
1c7d0 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c  managed internal
1c7e0 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ly..** The appli
1c7f0 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20  cation does not 
1c800 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62  need to worry ab
1c810 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20  out freeing the 
1c820 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76  result..** Howev
1c830 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74  er, the error st
1c840 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76  ring might be ov
1c850 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61  erwritten or dea
1c860 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73  llocated by.** s
1c870 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1c880 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  to other SQLite 
1c890 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69  interface functi
1c8a0 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65  ons.)^.**.** Whe
1c8b0 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64  n the serialized
1c8c0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1c8d0 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74 20  ] is in use, it 
1c8e0 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a 20  might be the.** 
1c8f0 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63 6f  case that a seco
1c900 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  nd error occurs 
1c910 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74 68  on a separate th
1c920 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e 0a  read in between.
1c930 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20 74  ** the time of t
1c940 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20 61  he first error a
1c950 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 74  nd the call to t
1c960 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 2e  hese interfaces.
1c970 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68 61  .** When that ha
1c980 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e  ppens, the secon
1c990 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20  d error will be 
1c9a0 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20 74  reported since t
1c9b0 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63  hese.** interfac
1c9c0 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72 74  es always report
1c9d0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
1c9e0 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f   result.  To avo
1c9f0 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63 68  id.** this, each
1ca00 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74 61   thread can obta
1ca10 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73 65  in exclusive use
1ca20 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
1ca30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a  e connection] D.
1ca40 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b  ** by invoking [
1ca50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e  sqlite3_mutex_en
1ca60 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62  ter]([sqlite3_db
1ca70 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66 6f  _mutex](D)) befo
1ca80 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20  re beginning.** 
1ca90 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e 76  to use D and inv
1caa0 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
1cab0 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c  utex_leave]([sql
1cac0 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
1cad0 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20  )) after.** all 
1cae0 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e 74  calls to the int
1caf0 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20 68  erfaces listed h
1cb00 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74 65  ere are complete
1cb10 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69  d..**.** If an i
1cb20 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20 77  nterface fails w
1cb30 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  ith SQLITE_MISUS
1cb40 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  E, that means th
1cb50 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77  e interface.** w
1cb60 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72  as invoked incor
1cb70 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61 70  rectly by the ap
1cb80 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74  plication.  In t
1cb90 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a  hat case, the.**
1cba0 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64 20   error code and 
1cbb0 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20 6d  message may or m
1cbc0 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a  ay not be set..*
1cbd0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1cbe0 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
1cbf0 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53  (sqlite3 *db);.S
1cc00 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1cc10 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65  lite3_extended_e
1cc20 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1cc30 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  db);.SQLITE_API 
1cc40 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1cc50 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
1cc60 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  e3*);.SQLITE_API
1cc70 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
1cc80 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
1cc90 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
1cca0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
1ccb0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
1ccc0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
1ccd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
1cce0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
1ccf0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
1cd00 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
1cd10 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
1cd20 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
1cd30 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
1cd40 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
1cd50 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
1cd60 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
1cd70 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
1cd80 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
1cd90 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
1cda0 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
1cdb0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
1cdc0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
1cdd0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
1cde0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
1cdf0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
1ce00 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
1ce10 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
1ce20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1ce30 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
1ce40 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
1ce50 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
1ce60 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
1ce70 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
1ce80 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
1ce90 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
1cea0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
1ceb0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
1cec0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
1ced0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
1cee0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
1cef0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
1cf00 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
1cf10 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1cf20 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
1cf30 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
1cf40 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
1cf50 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1cf60 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
1cf70 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
1cf80 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
1cf90 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
1cfa0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
1cfb0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
1cfc0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
1cfd0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
1cfe0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1cff0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
1d000 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
1d010 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
1d020 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
1d030 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
1d040 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  imits.**.** ^(Th
1d050 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
1d060 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
1d070 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
1d080 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
1d090 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
1d0a0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
1d0b0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
1d0c0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
1d0d0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
1d0e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
1d0f0 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
1d100 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
1d110 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
1d120 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
1d130 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
1d140 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
1d150 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
1d160 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
1d170 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
1d180 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
1d190 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
1d1a0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
1d1b0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
1d1c0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
1d1d0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
1d1e0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
1d1f0 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
1d200 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
1d210 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
1d220 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
1d230 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
1d240 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
1d250 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
1d260 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
1d270 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1d280 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
1d290 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
1d2a0 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
1d2b0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
1d2c0 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
1d2d0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
1d2e0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
1d2f0 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
1d300 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
1d310 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
1d320 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
1d330 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
1d340 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
1d350 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
1d360 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
1d370 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
1d380 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1d390 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
1d3a0 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
1d3b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
1d3c0 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
1d3d0 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
1d3e0 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
1d3f0 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
1d400 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
1d410 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
1d420 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
1d430 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
1d440 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
1d450 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
1d460 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
1d470 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
1d480 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
1d490 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
1d4a0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
1d4b0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
1d4c0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
1d4d0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
1d4e0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
1d4f0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
1d500 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
1d510 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
1d520 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
1d530 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
1d540 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
1d550 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
1d560 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
1d570 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
1d580 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
1d590 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
1d5a0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
1d5b0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
1d5c0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
1d5d0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
1d5e0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
1d5f0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
1d600 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
1d610 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
1d620 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
1d630 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
1d640 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
1d650 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
1d660 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
1d670 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
1d680 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
1d690 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
1d6a0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
1d6b0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
1d6c0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
1d6d0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
1d6e0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1d6f0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
1d700 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
1d710 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
1d720 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
1d730 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
1d740 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
1d750 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
1d760 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
1d770 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
1d780 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1d790 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
1d7a0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
1d7b0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
1d7c0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
1d7d0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
1d7e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1d7f0 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
1d800 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
1d810 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
1d820 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d830 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
1d840 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
1d850 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
1d860 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
1d870 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
1d880 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
1d890 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
1d8a0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
1d8b0 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
1d8c0 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
1d8d0 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
1d8e0 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
1d8f0 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
1d900 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
1d910 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
1d920 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
1d930 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
1d940 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
1d950 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
1d960 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
1d970 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
1d980 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74  ** <dl>.** ^(<dt
1d990 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
1d9a0 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
1d9b0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
1d9c0 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
1d9d0 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
1d9e0 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
1d9f0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1da00 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
1da10 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
1da20 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1da30 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
1da40 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
1da50 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
1da60 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1da70 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
1da80 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1da90 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1daa0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
1dab0 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
1dac0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
1dad0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
1dae0 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
1daf0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
1db00 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
1db10 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
1db20 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
1db30 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
1db40 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ^.**.** ^(<dt>SQ
1db50 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
1db60 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
1db70 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
1db80 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
1db90 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
1dba0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
1dbb0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1dbc0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
1dbd0 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a  D_SELECT</dt>.**
1dbe0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1dbf0 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
1dc00 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
1dc10 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1dc20 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1dc30 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1dc40 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
1dc50 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1dc60 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
1dc70 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
1dc80 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
1dc90 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
1dca0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
1dcb0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
1dcc0 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
1dcd0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
1dce0 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
1dcf0 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
1dd00 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
1dd10 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
1dd20 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
1dd30 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
1dd40 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
1dd50 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
1dd60 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
1dd70 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
1dd80 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
1dd90 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1dda0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  >SQLITE_LIMIT_AT
1ddb0 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  TACHED</dt>.** <
1ddc0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
1ddd0 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48  umber of [ATTACH
1dde0 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61   | attached data
1ddf0 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  bases].)^</dd>.*
1de00 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  *.** ^(<dt>SQLIT
1de10 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
1de20 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
1de30 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1de40 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
1de50 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
1de60 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
1de70 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
1de80 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
1de90 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1dea0 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
1deb0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
1dec0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1ded0 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
1dee0 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
1def0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
1df00 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  ment.)^.**.** ^(
1df10 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1df20 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f  _TRIGGER_DEPTH</
1df30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1df40 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
1df50 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72  recursion for tr
1df60 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  iggers.</dd>)^.*
1df70 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
1df80 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
1df90 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20  LENGTH          
1dfa0 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
1dfb0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1dfc0 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20  _SQL_LENGTH     
1dfd0 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
1dfe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1dff0 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20  T_COLUMN        
1e000 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
1e010 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1e020 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20  IT_EXPR_DEPTH   
1e030 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
1e040 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1e050 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
1e060 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a  ECT           4.
1e070 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1e080 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20  IMIT_VDBE_OP    
1e090 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
1e0a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e0b0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
1e0c0 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RG              
1e0d0 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
1e0e0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20  _LIMIT_ATTACHED 
1e0f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1e100 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
1e110 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
1e120 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20  TERN_LENGTH     
1e130 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
1e140 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
1e150 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20  E_NUMBER        
1e160 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
1e170 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
1e180 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
1e190 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     10../*.** CAP
1e1a0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67  I3REF: Compiling
1e1b0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
1e1c0 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
1e1d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  SQL statement co
1e1e0 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f  mpiler}.**.** To
1e1f0 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20   execute an SQL 
1e200 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66  query, it must f
1e210 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64  irst be compiled
1e220 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64   into a byte-cod
1e230 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69  e.** program usi
1e240 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  ng one of these 
1e250 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
1e260 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
1e270 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b  nt, "db", is a [
1e280 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e290 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72  ion] obtained fr
1e2a0 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75  om a.** prior su
1e2b0 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f  ccessful call to
1e2c0 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
1e2d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
1e2e0 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  _v2()] or.** [sq
1e2f0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
1e300 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63    The database c
1e310 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e  onnection must n
1e320 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f  ot have been clo
1e330 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  sed..**.** The s
1e340 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20  econd argument, 
1e350 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73  "zSql", is the s
1e360 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63  tatement to be c
1e370 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64  ompiled, encoded
1e380 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54  .** as either UT
1e390 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20  F-8 or UTF-16.  
1e3a0 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  The sqlite3_prep
1e3b0 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  are() and sqlite
1e3c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a  3_prepare_v2().*
1e3d0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65  * interfaces use
1e3e0 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69   UTF-8, and sqli
1e3f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20  te3_prepare16() 
1e400 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
1e410 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73  are16_v2().** us
1e420 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20  e UTF-16..**.** 
1e430 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72  ^If the nByte ar
1e440 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74  gument is less t
1e450 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a  han zero, then z
1e460 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74  Sql is read up t
1e470 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a  o the.** first z
1e480 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20  ero terminator. 
1e490 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  ^If nByte is non
1e4a0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
1e4b0 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  it is the maximu
1e4c0 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20  m.** number of  
1e4d0 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20  bytes read from 
1e4e0 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79  zSql.  ^When nBy
1e4f0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
1e500 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20  ve, the.** zSql 
1e510 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65  string ends at e
1e520 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20  ither the first 
1e530 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30  '\000' or '\u000
1e540 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a  0' character or.
1e550 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20  ** the nByte-th 
1e560 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20  byte, whichever 
1e570 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20  comes first. If 
1e580 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73  the caller knows
1e590 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70  .** that the sup
1e5a0 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20  plied string is 
1e5b0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20  nul-terminated, 
1e5c0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20  then there is a 
1e5d0 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d  small.** perform
1e5e0 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74  ance advantage t
1e5f0 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70  o be gained by p
1e600 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20  assing an nByte 
1e610 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a  parameter that.*
1e620 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68  * is equal to th
1e630 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
1e640 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73  s in the input s
1e650 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69  tring <i>includi
1e660 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75  ng</i>.** the nu
1e670 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74  l-terminator byt
1e680 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  es..**.** ^If pz
1e690 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
1e6a0 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
1e6b0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
1e6c0 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
1e6d0 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
1e6e0 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
1e6f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
1e700 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
1e710 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
1e720 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
1e730 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
1e740 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
1e750 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1e760 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
1e770 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
1e780 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
1e790 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
1e7a0 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
1e7b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1e7c0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
1e7d0 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
1e7e0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
1e7f0 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
1e800 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
1e810 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
1e820 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
1e830 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
1e840 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
1e850 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
1e860 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
1e870 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
1e880 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
1e890 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
1e8a0 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
1e8b0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1e8c0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
1e8d0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
1e8e0 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
1e8f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
1e900 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
1e910 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
1e920 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
1e930 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
1e940 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
1e950 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
1e960 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
1e970 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1e980 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
1e990 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
1e9a0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1e9b0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
1e9c0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
1e9d0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
1e9e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
1e9f0 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
1ea00 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
1ea10 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
1ea20 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
1ea30 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
1ea40 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
1ea50 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
1ea60 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
1ea70 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
1ea80 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
1ea90 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
1eaa0 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
1eab0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
1eac0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
1ead0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
1eae0 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
1eaf0 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
1eb00 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
1eb10 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
1eb20 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
1eb30 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
1eb40 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
1eb50 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
1eb60 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
1eb70 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
1eb80 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
1eb90 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
1eba0 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
1ebb0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
1ebc0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
1ebd0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
1ebe0 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
1ebf0 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
1ec00 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
1ec10 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
1ec20 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
1ec30 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
1ec40 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
1ec50 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
1ec60 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
1ec70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1ec80 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
1ec90 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
1eca0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
1ecb0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
1ecc0 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
1ecd0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
1ece0 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
1ecf0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
1ed00 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
1ed10 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
1ed20 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
1ed30 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
1ed40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
1ed50 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
1ed60 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
1ed70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1ed80 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
1ed90 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
1eda0 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
1edb0 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
1edc0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
1edd0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
1ede0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
1edf0 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
1ee00 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1ee10 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
1ee20 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
1ee30 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
1ee40 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
1ee50 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
1ee60 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
1ee70 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
1ee80 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
1ee90 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
1eea0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
1eeb0 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
1eec0 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
1eed0 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
1eee0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
1eef0 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
1ef00 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
1ef10 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
1ef20 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
1ef30 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
1ef40 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
1ef50 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
1ef60 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
1ef70 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
1ef80 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
1ef90 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
1efa0 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
1efb0 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
1efc0 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
1efd0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
1efe0 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
1eff0 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
1f000 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
1f010 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
1f020 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
1f030 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
1f040 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
1f050 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
1f060 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
1f070 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
1f080 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
1f090 4e 41 42 4c 45 5f 53 54 41 54 32 5d 20 63 6f 6d  NABLE_STAT2] com
1f0a0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1f0b0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
1f0c0 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  the .** </li>.**
1f0d0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ol>.*/.SQLITE
1f0e0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1f0f0 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
1f100 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
1f110 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
1f120 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
1f130 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1f140 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
1f150 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
1f160 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
1f170 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
1f180 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
1f190 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
1f1a0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
1f1b0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
1f1c0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
1f1d0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
1f1e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
1f1f0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
1f200 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
1f210 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
1f220 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
1f230 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
1f240 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
1f250 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1f260 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1f270 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1f280 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1f290 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1f2a0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
1f2b0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1f2c0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1f2d0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1f2e0 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1f2f0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1f300 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1f310 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1f320 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1f330 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
1f340 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1f350 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1f360 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1f370 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
1f380 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1f390 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
1f3a0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1f3b0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1f3c0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1f3d0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
1f3e0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1f3f0 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
1f400 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1f410 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1f420 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1f430 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1f440 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1f450 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1f460 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1f470 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1f480 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
1f490 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1f4a0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1f4b0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1f4c0 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
1f4d0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1f4e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
1f4f0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
1f500 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
1f510 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
1f520 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
1f530 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
1f540 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
1f550 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
1f560 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
1f570 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
1f580 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
1f590 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
1f5a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
1f5b0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
1f5c0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
1f5d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
1f5e0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
1f5f0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
1f600 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
1f610 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
1f620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1f630 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
1f640 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54  ent SQL.**.** ^T
1f650 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
1f660 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
1f670 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
1f680 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
1f690 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
1f6a0 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
1f6b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1f6c0 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
1f6d0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
1f6e0 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
1f6f0 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
1f700 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
1f710 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1f720 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  _v2()]..*/.SQLIT
1f730 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
1f740 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
1f750 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
1f760 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
1f770 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
1f780 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
1f790 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
1f7a0 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  tabase.**.** ^Th
1f7b0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
1f7c0 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72  eadonly(X) inter
1f7d0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
1f7e0 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
1f7f0 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
1f800 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
1f810 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
1f820 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
1f830 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
1f840 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
1f850 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
1f860 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
1f870 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
1f880 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
1f890 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
1f8a0 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
1f8b0 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
1f8c0 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
1f8d0 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
1f8e0 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
1f8f0 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
1f900 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
1f910 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
1f920 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
1f930 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
1f940 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
1f950 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
1f960 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
1f970 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
1f980 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
1f990 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
1f9a0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1f9b0 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
1f9c0 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
1f9d0 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
1f9e0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1f9f0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
1fa00 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
1fa10 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
1fa20 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
1fa30 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
1fa40 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
1fa50 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
1fa60 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
1fa70 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
1fa80 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
1fa90 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
1faa0 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
1fab0 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
1fac0 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
1fad0 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
1fae0 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
1faf0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
1fb00 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
1fb10 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
1fb20 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
1fb30 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
1fb40 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
1fb50 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
1fb60 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
1fb70 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
1fb80 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
1fb90 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
1fba0 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
1fbb0 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
1fbc0 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
1fbd0 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
1fbe0 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
1fbf0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
1fc00 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
1fc10 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
1fc20 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
1fc30 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
1fc40 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
1fc50 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
1fc60 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
1fc70 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
1fc80 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
1fc90 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
1fca0 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
1fcb0 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  k..*/.SQLITE_API
1fcc0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d   int sqlite3_stm
1fcd0 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
1fce0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
1fcf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1fd00 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
1fd10 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
1fd20 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
1fd30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
1fd40 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
1fd50 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
1fd60 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
1fd70 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
1fd80 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
1fd90 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
1fda0 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
1fdb0 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
1fdc0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
1fdd0 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
1fde0 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
1fdf0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
1fe00 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
1fe10 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
1fe20 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
1fe30 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
1fe40 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
1fe50 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
1fe60 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
1fe70 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
1fe80 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
1fe90 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
1fea0 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
1feb0 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
1fec0 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
1fed0 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
1fee0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1fef0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
1ff00 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
1ff10 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
1ff20 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
1ff30 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
1ff40 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
1ff50 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
1ff60 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
1ff70 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
1ff80 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
1ff90 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1ffa0 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
1ffb0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
1ffc0 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
1ffd0 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
1ffe0 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
1fff0 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
20000 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
20010 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
20020 20 20 41 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74    A internal mut
20030 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
20040 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
20050 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
20060 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
20070 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
20080 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
20090 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
200a0 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
200b0 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
200c0 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
200d0 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
200e0 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
200f0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
20100 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
20110 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
20120 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
20130 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
20140 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
20150 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
20160 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
20170 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
20180 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
20190 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
201a0 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
201b0 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
201c0 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
201d0 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
201e0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
201f0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
20200 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
20210 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
20220 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
20230 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
20240 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
20250 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
20260 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
20270 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
20280 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
20290 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
202a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
202b0 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
202c0 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
202d0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
202e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
202f0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
20300 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
20310 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
20320 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
20330 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
20340 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
20350 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
20360 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
20370 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
20380 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
20390 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
203a0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
203b0 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
203c0 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
203d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
203e0 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
203f0 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
20400 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
20410 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
20420 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
20430 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
20440 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
20450 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
20460 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
20470 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
20480 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
20490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
204a0 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
204b0 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
204c0 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
204d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
204e0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
204f0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
20500 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
20510 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
20520 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
20530 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
20540 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
20550 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
20560 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
20570 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
20580 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
20590 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
205a0 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
205b0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
205c0 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
205d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
205e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
205f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
20600 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
20610 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
20620 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
20630 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
20640 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
20650 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
20660 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
20670 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
20680 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
20690 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
206a0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
206b0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
206c0 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
206d0 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
206e0 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
206f0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
20700 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
20710 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
20720 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
20730 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
20740 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
20750 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
20760 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
20770 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
20780 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
20790 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
207a0 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
207b0 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
207c0 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
207d0 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
207e0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
207f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
20800 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
20810 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20820 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
20830 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
20840 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
20850 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
20860 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
20870 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
20880 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
20890 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
208a0 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
208b0 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
208c0 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
208d0 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
208e0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
208f0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
20900 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
20910 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
20920 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
20930 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
20940 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
20950 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
20960 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
20970 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
20980 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
20990 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
209a0 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
209b0 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
209c0 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
209d0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
209e0 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
209f0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
20a00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
20a10 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
20a20 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
20a30 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
20a40 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
20a50 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
20a60 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
20a70 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
20a80 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
20a90 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
20aa0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
20ab0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
20ac0 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
20ad0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
20ae0 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
20af0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
20b00 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
20b10 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
20b20 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
20b30 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
20b40 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
20b50 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
20b60 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
20b70 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
20b80 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
20b90 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
20ba0 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
20bb0 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
20bc0 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
20bd0 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
20be0 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
20bf0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
20c00 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
20c10 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
20c20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
20c30 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
20c40 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
20c50 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
20c60 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
20c70 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
20c80 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
20c90 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
20ca0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
20cb0 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
20cc0 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
20cd0 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
20ce0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
20cf0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
20d00 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
20d10 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ter..**.** ^(In 
20d20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
20d30 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
20d40 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
20d50 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
20d60 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
20d70 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
20d80 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
20d90 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
20da0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
20db0 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
20dc0 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
20dd0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
20de0 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
20df0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
20e00 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
20e10 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
20e20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
20e30 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
20e40 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
20e50 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
20e60 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ator..**.** ^The
20e70 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
20e80 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
20e90 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
20ea0 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64  bind_text(), and
20eb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
20ec0 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20 64  _text16() is a d
20ed0 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20 74  estructor used t
20ee0 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  o dispose of the
20ef0 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69   BLOB or.** stri
20f00 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65 20  ng after SQLite 
20f10 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
20f20 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74  h it.  ^The dest
20f30 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64  ructor is called
20f40 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f  .** to dispose o
20f50 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74  f the BLOB or st
20f60 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ring even if the
20f70 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
20f80 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a  _bind_blob(),.**
20f90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
20fa0 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33  xt(), or sqlite3
20fb0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66  _bind_text16() f
20fc0 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74  ails.  .** ^If t
20fd0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
20fe0 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63  t is.** the spec
20ff0 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  ial value [SQLIT
21000 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20  E_STATIC], then 
21010 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74  SQLite assumes t
21020 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72  hat the.** infor
21030 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61  mation is in sta
21040 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73  tic, unmanaged s
21050 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
21060 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65  t need to be fre
21070 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ed..** ^If the f
21080 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61  ifth argument ha
21090 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c  s the value [SQL
210a0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20  ITE_TRANSIENT], 
210b0 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d  then.** SQLite m
210c0 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69  akes its own pri
210d0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
210e0 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c   data immediatel
210f0 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65  y, before.** the
21100 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
21110 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
21120 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
21130 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
21140 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69  lob() routine bi
21150 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65  nds a BLOB of le
21160 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69  ngth N that.** i
21170 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65  s filled with ze
21180 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c  roes.  ^A zerobl
21190 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64 20  ob uses a fixed 
211a0 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79  amount of memory
211b0 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74  .** (just an int
211c0 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73  eger to hold its
211d0 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20   size) while it 
211e0 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73  is being process
211f0 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73  ed..** Zeroblobs
21200 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f   are intended to
21210 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65 68   serve as placeh
21220 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73  olders for BLOBs
21230 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e   whose.** conten
21240 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74 74  t is later writt
21250 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  en using.** [sql
21260 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c  ite3_blob_open |
21270 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f   incremental BLO
21280 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e  B I/O] routines.
21290 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20  .** ^A negative 
212a0 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65  value for the ze
212b0 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69  roblob results i
212c0 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20  n a zero-length 
212d0 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  BLOB..**.** ^If 
212e0 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74  any of the sqlit
212f0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
21300 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20  ines are called 
21310 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
21320 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b  ter.** for the [
21330 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
21340 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72  nt] or with a pr
21350 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
21360 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73   for which.** [s
21370 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
21380 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d  as been called m
21390 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61  ore recently tha
213a0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
213b0 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ()],.** then the
213c0 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72   call will retur
213d0 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
213e0 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74  ].  If any sqlit
213f0 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f  e3_bind_().** ro
21400 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64 20  utine is passed 
21410 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
21420 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20  ement] that has 
21430 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20  been finalized, 
21440 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73  the.** result is
21450 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
21460 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e  robably harmful.
21470 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73  .**.** ^Bindings
21480 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64   are not cleared
21490 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
214a0 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e  _reset()] routin
214b0 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70  e..** ^Unbound p
214c0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e  arameters are in
214d0 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c  terpreted as NUL
214e0 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
214f0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75  lite3_bind_* rou
21500 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
21510 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63  LITE_OK] on succ
21520 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72  ess or an.** [er
21530 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79  ror code] if any
21540 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67  thing goes wrong
21550 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41  ..** ^[SQLITE_RA
21560 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64  NGE] is returned
21570 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
21580 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75  r.** index is ou
21590 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53  t of range.  ^[S
215a0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20  QLITE_NOMEM] is 
215b0 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c  returned if mall
215c0 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a  oc() fails..**.*
215d0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
215e0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
215f0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a  ter_count()],.**
21600 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
21610 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d  arameter_name()]
21620 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  , and [sqlite3_b
21630 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
21640 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
21650 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
21660 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69  3_bind_blob(sqli
21670 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
21680 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
21690 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
216a0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
216b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
216c0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
216d0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
216e0 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  le);.SQLITE_API 
216f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21700 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
21710 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53  t*, int, int);.S
21720 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
21730 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34  lite3_bind_int64
21740 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21750 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  int, sqlite3_int
21760 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
21770 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21780 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74  _null(sqlite3_st
21790 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  mt*, int);.SQLIT
217a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
217b0 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
217c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
217d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
217e0 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
217f0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
21800 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
21810 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
21820 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
21830 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
21840 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
21850 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
21860 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
21870 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
21880 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74  int, const sqlit
21890 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
218a0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
218b0 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
218c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
218d0 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
218e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
218f0 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
21900 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
21910 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
21920 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
21930 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
21940 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
21950 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
21960 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
21970 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
21980 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
21990 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
219a0 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
219b0 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
219c0 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
219d0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
219e0 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
219f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
21a00 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
21a10 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
21a20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
21a30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
21a40 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
21a50 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
21a60 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
21a70 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
21a80 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
21a90 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
21aa0 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
21ab0 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
21ac0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
21ad0 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
21ae0 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
21af0 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
21b00 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
21b10 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
21b20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
21b30 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
21b40 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
21b50 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
21b60 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
21b70 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
21b80 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
21b90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
21ba0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
21bb0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
21bc0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
21bd0 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73  arameter_count(s
21be0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
21bf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
21c00 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50  Name Of A Host P
21c10 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e  arameter.**.** ^
21c20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
21c30 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
21c40 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72  P,N) interface r
21c50 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61  eturns.** the na
21c60 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b  me of the N-th [
21c70 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69  SQL parameter] i
21c80 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  n the [prepared 
21c90 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a  statement] P..**
21ca0 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72   ^(SQL parameter
21cb0 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f  s of the form "?
21cc0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
21cd0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
21ce0 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d  A".** have a nam
21cf0 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73  e which is the s
21d00 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20  tring "?NNN" or 
21d10 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
21d20 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65   or "$AAA".** re
21d30 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49  spectively..** I
21d40 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
21d50 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f  he initial ":" o
21d60 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20  r "$" or "@" or 
21d70 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64  "?".** is includ
21d80 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
21d90 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61  e name.)^.** ^Pa
21da0 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
21db0 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74  form "?" without
21dc0 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74   a following int
21dd0 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d  eger have no nam
21de0 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66  e.** and are ref
21df0 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d  erred to as "nam
21e00 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79  eless" or "anony
21e10 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22  mous parameters"
21e20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
21e30 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  st host paramete
21e40 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f  r has an index o
21e50 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a  f 1, not 0..**.*
21e60 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20  * ^If the value 
21e70 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
21e80 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68  e or if the N-th
21e90 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
21ea0 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20   nameless, then 
21eb0 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64  NULL is returned
21ec0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
21ed0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c   string is.** al
21ee0 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e  ways in UTF-8 en
21ef0 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74  coding even if t
21f00 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74  he named paramet
21f10 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e  er was.** origin
21f20 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20 61  ally specified a
21f30 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c  s UTF-16 in [sql
21f40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
21f50 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
21f60 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
21f70 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
21f80 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
21f90 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
21fa0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
21fb0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
21fc0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
21fd0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
21fe0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
21ff0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
22000 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
22010 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
22020 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65  eter_name(sqlite
22030 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a  3_stmt*, int);..
22040 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22050 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d  Index Of A Param
22060 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76 65  eter With A Give
22070 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65  n Name.**.** ^Re
22080 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f  turn the index o
22090 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74  f an SQL paramet
220a0 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d  er given its nam
220b0 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65  e.  ^The.** inde
220c0 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  x value returned
220d0 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72   is suitable for
220e0 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63 6f   use as the seco
220f0 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  nd.** parameter 
22100 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  to [sqlite3_bind
22110 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
22120 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a  nd()].  ^A zero.
22130 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
22140 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61  f no matching pa
22150 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64  rameter is found
22160 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
22170 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62  r.** name must b
22180 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38  e given in UTF-8
22190 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69   even if the ori
221a0 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a  ginal statement.
221b0 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64 20  ** was prepared 
221c0 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74  from UTF-16 text
221d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
221e0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
221f0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
22200 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
22210 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
22220 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
22230 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
22240 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a  count()], and.**
22250 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
22260 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
22270 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
22280 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
22290 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
222a0 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
222b0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
222c0 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
222d0 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
222e0 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
222f0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
22300 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
22310 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
22320 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
22330 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
22340 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
22350 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
22360 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
22370 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
22380 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
22390 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
223a0 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
223b0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
223c0 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54  o NULL..*/.SQLIT
223d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
223e0 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
223f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
22400 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22410 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75  : Number Of Colu
22420 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mns In A Result 
22430 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  Set.**.** ^Retur
22440 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
22450 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
22460 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e  esult set return
22470 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72  ed by the.** [pr
22480 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
22490 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ]. ^This routine
224a0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70 53   returns 0 if pS
224b0 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a  tmt is an SQL.**
224c0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
224d0 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20  does not return 
224e0 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c  data (for exampl
224f0 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a  e an [UPDATE])..
22500 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
22510 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f  [sqlite3_data_co
22520 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45  unt()].*/.SQLITE
22530 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
22540 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71  _column_count(sq
22550 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
22560 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
22570 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65  REF: Column Name
22580 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
22590 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
225a0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
225b0 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64  he name assigned
225c0 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72   to a particular
225d0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68   column.** in th
225e0 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
225f0 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  a [SELECT] state
22600 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69  ment.  ^The sqli
22610 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
22620 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72  ).** interface r
22630 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
22640 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   to a zero-termi
22650 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69  nated UTF-8 stri
22660 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ng.** and sqlite
22670 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
22680 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
22690 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65  ter to a zero-te
226a0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
226b0 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
226c0 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
226d0 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72 65   is the [prepare
226e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
226f0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
22700 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
22710 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63  tement. ^The sec
22720 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
22730 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e   the.** column n
22740 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66  umber.  ^The lef
22750 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  tmost column is 
22760 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20  number 0..**.** 
22770 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74  ^The returned st
22780 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20  ring pointer is 
22790 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68  valid until eith
227a0 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  er the [prepared
227b0 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69   statement].** i
227c0 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b  s destroyed by [
227d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
227e0 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  ()] or until the
227f0 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
22800 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
22810 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
22820 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
22830 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
22840 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
22850 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
22860 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
22870 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
22880 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
22890 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
228a0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
228b0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
228c0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
228d0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
228e0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
228f0 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
22900 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
22910 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
22920 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
22930 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
22940 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
22950 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
22960 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
22970 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
22980 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
22990 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
229a0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
229b0 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
229c0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
229d0 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
229e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
229f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
22a00 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
22a10 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
22a20 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20   N);.SQLITE_API 
22a30 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
22a40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
22a50 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
22a60 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
22a70 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
22a80 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
22a90 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
22aa0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
22ab0 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
22ac0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
22ad0 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
22ae0 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
22af0 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
22b00 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
22b10 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
22b20 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
22b30 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
22b40 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
22b50 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
22b60 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
22b70 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
22b80 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
22b90 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
22ba0 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
22bb0 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
22bc0 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
22bd0 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
22be0 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
22bf0 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
22c00 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
22c10 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
22c20 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
22c30 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
22c40 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
22c50 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
22c60 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
22c70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22c80 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
22c90 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
22ca0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
22cb0 74 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66  til the same inf
22cc0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75  ormation is requ
22cd0 65 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69  ested.** again i
22ce0 6e 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e  n a different en
22cf0 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54  coding..**.** ^T
22d00 68 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65  he names returne
22d10 64 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e  d are the origin
22d20 61 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61  al un-aliased na
22d30 6d 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61  mes of the.** da
22d40 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61  tabase, table, a
22d50 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  nd column..**.**
22d60 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
22d70 6d 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e  ment to these in
22d80 74 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70  terfaces is a [p
22d90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22da0 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  t]..** ^These fu
22db0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69  nctions return i
22dc0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
22dd0 20 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20   the Nth result 
22de0 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20  column returned 
22df0 62 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  by.** the statem
22e00 65 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ent, where N is 
22e10 74 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74  the second funct
22e20 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  ion argument..**
22e30 20 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20   ^The left-most 
22e40 63 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e  column is column
22e50 20 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75   0 for these rou
22e60 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  tines..**.** ^If
22e70 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
22e80 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20  returned by the 
22e90 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20  statement is an 
22ea0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a  expression or.**
22eb0 20 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73   subquery and is
22ec0 20 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61   not a column va
22ed0 6c 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66  lue, then all of
22ee0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
22ef0 20 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e   return.** NULL.
22f00 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
22f10 20 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75   might also retu
22f20 72 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d  rn NULL if a mem
22f30 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
22f40 72 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20  rror.** occurs. 
22f50 20 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65   ^Otherwise, the
22f60 79 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  y return the nam
22f70 65 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65  e of the attache
22f80 64 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  d database, tabl
22f90 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20  e,.** or column 
22fa0 74 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c  that query resul
22fb0 74 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74  t column was ext
22fc0 72 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a  racted from..**.
22fd0 2a 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20  ** ^As with all 
22fe0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49  other SQLite API
22ff0 73 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e  s, those whose n
23000 61 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31  ames end with "1
23010 36 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46  6" return.** UTF
23020 2d 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69  -16 encoded stri
23030 6e 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65  ngs and the othe
23040 72 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  r functions retu
23050 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20  rn UTF-8..**.** 
23060 5e 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20  ^These APIs are 
23070 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
23080 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
23090 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
230a0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
230b0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
230c0 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
230d0 65 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a  essor symbol..**
230e0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
230f0 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
23100 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74  one or more of t
23110 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67  hese routines ag
23120 61 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a  ainst the same.*
23130 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  * prepared state
23140 6d 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20  ment and column 
23150 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
23160 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
23170 73 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e  s are.** undefin
23180 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ed..**.** If two
23190 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
231a0 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
231b0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
231c0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
231d0 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61  me | column meta
231e0 64 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d  data interfaces]
231f0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
23200 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23210 6d 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74  ment] and result
23220 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68   column.** at th
23230 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
23240 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
23250 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53   undefined..*/.S
23260 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
23270 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
23280 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
23290 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
232a0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
232b0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
232c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74  lite3_column_dat
232d0 61 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c  abase_name16(sql
232e0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
232f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
23300 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
23310 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d  column_table_nam
23320 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
23330 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
23340 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
23350 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
23360 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
23370 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
23380 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
23390 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
233a0 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73  mn_origin_name(s
233b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
233c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
233d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
233e0 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
233f0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
23400 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  tmt*,int);../*.*
23410 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c  * CAPI3REF: Decl
23420 61 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66  ared Datatype Of
23430 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
23440 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73  **.** ^(The firs
23450 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  t parameter is a
23460 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
23470 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69  ment]..** If thi
23480 73 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  s statement is a
23490 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
234a0 65 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20  ent and the Nth 
234b0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a  column of the.**
234c0 20 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74   returned result
234d0 20 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45   set of that [SE
234e0 4c 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65  LECT] is a table
234f0 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a   column (not an.
23500 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
23510 20 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20   subquery) then 
23520 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70  the declared typ
23530 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a  e of the table.*
23540 2a 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75  * column is retu
23550 72 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65  rned.)^  ^If the
23560 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74   Nth column of t
23570 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73  he result set is
23580 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
23590 6e 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74  n or subquery, t
235a0 68 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  hen a NULL point
235b0 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  er is returned..
235c0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
235d0 20 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79   string is alway
235e0 73 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e  s UTF-8 encoded.
235f0 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61  .**.** ^(For exa
23600 6d 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20  mple, given the 
23610 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a  database schema:
23620 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41  .**.** CREATE TA
23630 42 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e  BLE t1(c1 VARIAN
23640 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68  T);.**.** and th
23650 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74  e following stat
23660 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
23670 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45  iled:.**.** SELE
23680 43 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52  CT c1 + 1, c1 FR
23690 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69  OM t1;.**.** thi
236a0 73 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20  s routine would 
236b0 72 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e  return the strin
236c0 67 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20  g "VARIANT" for 
236d0 74 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c  the second resul
236e0 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  t.** column (i==
236f0 31 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70  1), and a NULL p
23700 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66  ointer for the f
23710 69 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75  irst result colu
23720 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a  mn (i==0).)^.**.
23730 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
23740 64 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65  dynamic run-time
23750 20 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75   typing.  ^So ju
23760 73 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c  st because a col
23770 75 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72  umn.** is declar
23780 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20  ed to contain a 
23790 70 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20  particular type 
237a0 64 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68  does not mean th
237b0 61 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73  at the.** data s
237c0 74 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f  tored in that co
237d0 6c 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64  lumn is of the d
237e0 65 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53  eclared type.  S
237f0 51 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f  QLite is.** stro
23800 6e 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20  ngly typed, but 
23810 74 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79  the typing is dy
23820 6e 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63  namic not static
23830 2e 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61  .  ^Type.** is a
23840 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69  ssociated with i
23850 6e 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73  ndividual values
23860 2c 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63  , not with the c
23870 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65  ontainers.** use
23880 64 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20  d to hold those 
23890 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  values..*/.SQLIT
238a0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
238b0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
238c0 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65  _decltype(sqlite
238d0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51  3_stmt*,int);.SQ
238e0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
238f0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
23900 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73  umn_decltype16(s
23910 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
23920 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23930 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20  EF: Evaluate An 
23940 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL Statement.**
23950 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65  .** After a [pre
23960 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23970 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72   has been prepar
23980 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a  ed using either.
23990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
239a0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
239b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
239c0 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
239d0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
239e0 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65  terfaces [sqlite
239f0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
23a00 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
23a10 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63  16()], this func
23a20 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20  tion.** must be 
23a30 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f  called one or mo
23a40 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c  re times to eval
23a50 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  uate the stateme
23a60 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65  nt..**.** The de
23a70 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68  tails of the beh
23a80 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c  avior of the sql
23a90 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65  ite3_step() inte
23aa0 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20  rface depend.** 
23ab0 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73  on whether the s
23ac0 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65  tatement was pre
23ad0 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20  pared using the 
23ae0 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72  newer "v2" inter
23af0 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  face.** [sqlite3
23b00 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
23b10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
23b20 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74  are16_v2()] or t
23b30 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a  he older legacy.
23b40 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71  ** interface [sq
23b50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
23b60 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
23b70 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65  epare16()].  The
23b80 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e   use of the.** n
23b90 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  ew "v2" interfac
23ba0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
23bb0 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61   for new applica
23bc0 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65  tions but the le
23bd0 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
23be0 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20  e will continue 
23bf0 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
23c00 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c  .**.** ^In the l
23c10 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
23c20 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
23c30 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72  e will be either
23c40 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a   [SQLITE_BUSY],.
23c50 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ** [SQLITE_DONE]
23c60 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20  , [SQLITE_ROW], 
23c70 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20  [SQLITE_ERROR], 
23c80 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  or [SQLITE_MISUS
23c90 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  E]..** ^With the
23ca0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
23cb0 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65   any of the othe
23cc0 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  r [result codes]
23cd0 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
23ce0 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d   result codes] m
23cf0 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64  ight be returned
23d00 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20   as well..**.** 
23d10 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d  ^[SQLITE_BUSY] m
23d20 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61  eans that the da
23d30 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61  tabase engine wa
23d40 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75  s unable to acqu
23d50 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ire the.** datab
23d60 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65  ase locks it nee
23d70 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62  ds to do its job
23d80 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65  .  ^If the state
23d90 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49  ment is a [COMMI
23da0 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20  T].** or occurs 
23db0 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78  outside of an ex
23dc0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
23dd0 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e  on, then you can
23de0 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74   retry the.** st
23df0 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65  atement.  If the
23e00 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f   statement is no
23e10 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64  t a [COMMIT] and
23e20 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
23e30 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
23e40 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
23e50 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
23e60 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
23e70 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
23e80 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
23e90 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
23ea0 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
23eb0 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
23ec0 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
23ed0 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
23ee0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
23ef0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
23f00 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
23f10 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
23f20 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
23f30 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
23f40 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
23f50 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
23f60 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
23f70 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
23f80 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
23f90 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
23fa0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
23fb0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
23fc0 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
23fd0 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
23fe0 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
23ff0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
24000 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
24010 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
24020 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
24030 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
24040 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
24050 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
24060 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
24070 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
24080 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
24090 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
240a0 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
240b0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
240c0 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
240d0 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
240e0 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
240f0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
24100 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
24110 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
24120 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
24130 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
24140 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
24150 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
24160 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
24170 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
24180 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
24190 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
241a0 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
241b0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
241c0 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
241d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
241e0 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
241f0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
24200 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
24210 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
24220 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
24230 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
24240 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
24250 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
24260 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
24270 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
24280 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
24290 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
242a0 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
242b0 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
242c0 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
242d0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
242e0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
242f0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
24300 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
24310 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
24320 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
24330 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
24340 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
24350 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
24360 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
24370 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
24380 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
24390 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
243a0 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
243b0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
243c0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
243d0 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
243e0 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
243f0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
24400 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
24410 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
24420 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
24430 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
24440 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
24450 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
24460 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
24470 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
24480 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
24490 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
244a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
244b0 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
244c0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
244d0 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
244e0 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
244f0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
24500 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
24510 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
24520 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
24530 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
24540 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
24550 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
24560 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
24570 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
24580 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
24590 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
245a0 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
245b0 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
245c0 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e  after version 3.
245d0 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
245e0 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20  step() began.** 
245f0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
24600 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61  _reset()] automa
24610 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
24620 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
24630 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75  her.** than retu
24640 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49  rning [SQLITE_MI
24650 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20  SUSE].  This is 
24660 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61  not considered a
24670 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
24680 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20  * break because 
24690 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  any application 
246a0 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76  that ever receiv
246b0 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53  es an SQLITE_MIS
246c0 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20  USE error.** is 
246d0 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69  broken by defini
246e0 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49  tion.  The [SQLI
246f0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45  TE_OMIT_AUTORESE
24700 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
24710 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65  option.** can be
24720 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65   used to restore
24730 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
24740 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  vior..**.** <b>G
24750 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
24760 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
24770 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
24780 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
24790 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
247a0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
247b0 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
247c0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
247d0 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
247e0 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
247f0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
24800 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
24810 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
24820 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
24830 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
24840 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24850 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
24860 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
24870 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
24880 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
24890 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
248a0 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
248b0 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
248c0 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
248d0 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
248e0 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
248f0 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
24900 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
24910 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
24920 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
24930 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
24940 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
24950 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
24960 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
24970 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
24980 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
24990 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
249a0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
249b0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
249c0 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
249d0 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
249e0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
249f0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
24a00 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
24a10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
24a20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
24a30 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
24a40 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
24a50 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
24a60 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
24a70 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
24a80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
24a90 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
24aa0 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
24ab0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
24ac0 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
24ad0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
24ae0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
24af0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
24b00 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
24b10 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
24b20 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
24b30 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
24b40 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
24b50 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
24b60 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
24b70 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
24b80 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
24b90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
24ba0 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
24bb0 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
24bc0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
24bd0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
24be0 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
24bf0 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
24c00 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
24c10 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
24c20 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
24c30 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
24c40 72 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  r..**.** See als
24c50 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
24c60 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53  mn_count()].*/.S
24c70 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
24c80 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
24c90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
24ca0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
24cb0 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e  PI3REF: Fundamen
24cc0 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a  tal Datatypes.**
24cd0 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
24ce0 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45  E_TEXT.**.** ^(E
24cf0 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51  very value in SQ
24d00 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20  Lite has one of 
24d10 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c  five fundamental
24d20 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a   datatypes:.**.*
24d30 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36  * <ul>.** <li> 6
24d40 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
24d50 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  eger.** <li> 64-
24d60 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e  bit IEEE floatin
24d70 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a  g point number.*
24d80 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a  * <li> string.**
24d90 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c   <li> BLOB.** <l
24da0 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e  i> NULL.** </ul>
24db0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  )^.**.** These c
24dc0 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64  onstants are cod
24dd0 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74  es for each of t
24de0 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a  hose types..**.*
24df0 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  * Note that the 
24e00 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73  SQLITE_TEXT cons
24e10 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73  tant was also us
24e20 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72  ed in SQLite ver
24e30 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20  sion 2.** for a 
24e40 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65  completely diffe
24e50 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53  rent meaning.  S
24e60 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e  oftware that lin
24e70 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a  ks against both.
24e80 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
24e90 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76  n 2 and SQLite v
24ea0 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20  ersion 3 should 
24eb0 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  use SQLITE3_TEXT
24ec0 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f  , not.** SQLITE_
24ed0 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  TEXT..*/.#define
24ee0 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20   SQLITE_INTEGER 
24ef0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
24f00 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65  E_FLOAT    2.#de
24f10 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42  fine SQLITE_BLOB
24f20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
24f30 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35  QLITE_NULL     5
24f40 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54  .#ifdef SQLITE_T
24f50 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  EXT.# undef SQLI
24f60 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20  TE_TEXT.#else.# 
24f70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45  define SQLITE_TE
24f80 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a  XT     3.#endif.
24f90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f  #define SQLITE3_
24fa0 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a  TEXT     3../*.*
24fb0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
24fc0 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41  lt Values From A
24fd0 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52   Query.** KEYWOR
24fe0 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65  DS: {column acce
24ff0 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  ss functions}.**
25000 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
25010 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73  es form the "res
25020 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66 61  ult set" interfa
25030 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ce..**.** ^These
25040 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
25050 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
25060 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75  ut a single colu
25070 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  mn of the curren
25080 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  t.** result row 
25090 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e  of a query.  ^In
250a0 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65 20   every case the 
250b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
250c0 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  s a pointer.** t
250d0 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  o the [prepared 
250e0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
250f0 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74  is being evaluat
25100 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33  ed (the [sqlite3
25110 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20  _stmt*].** that 
25120 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f  was returned fro
25130 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  m [sqlite3_prepa
25140 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  re_v2()] or one 
25150 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  of its variants)
25160 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f  .** and the seco
25170 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
25180 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
25190 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68  column for which
251a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
251b0 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
251c0 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  ed. ^The leftmos
251d0 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  t column of the 
251e0 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20 74  result set has t
251f0 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e  he index 0..** ^
25200 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  The number of co
25210 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
25220 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  ult can be deter
25230 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  mined using.** [
25240 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
25250 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49  ount()]..**.** I
25260 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  f the SQL statem
25270 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72  ent does not cur
25280 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20  rently point to 
25290 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20  a valid row, or 
252a0 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  if the.** column
252b0 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
252c0 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75   range, the resu
252d0 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  lt is undefined.
252e0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
252f0 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63  es may only be c
25300 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d  alled when the m
25310 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
25320 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
25330 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
25340 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
25350 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20   and neither.** 
25360 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
25370 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  ] nor [sqlite3_f
25380 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20  inalize()] have 
25390 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73  been called subs
253a0 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20  equently..** If 
253b0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
253c0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
253d0 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f   after [sqlite3_
253e0 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b  reset()] or.** [
253f0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
25400 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71  ()] or after [sq
25410 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
25420 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f  s returned.** so
25430 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
25440 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  an [SQLITE_ROW],
25450 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
25460 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49   undefined..** I
25470 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  f [sqlite3_step(
25480 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
25490 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
254a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a  te3_finalize()].
254b0 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72  ** are called fr
254c0 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20 74  om a different t
254d0 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20  hread while any 
254e0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
254f0 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67  s.** are pending
25500 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
25510 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
25520 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
25530 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
25540 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
25550 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ns the.** [SQLIT
25560 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61  E_INTEGER | data
25570 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74  type code] for t
25580 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20  he initial data 
25590 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72  type.** of the r
255a0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e  esult column.  ^
255b0 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c  The returned val
255c0 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  ue is one of [SQ
255d0 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a  LITE_INTEGER],.*
255e0 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d  * [SQLITE_FLOAT]
255f0 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c  , [SQLITE_TEXT],
25600 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20   [SQLITE_BLOB], 
25610 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d  or [SQLITE_NULL]
25620 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20  .  The value.** 
25630 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
25640 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
25650 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e  ) is only meanin
25660 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a  gful if no type.
25670 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68  ** conversions h
25680 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73 20  ave occurred as 
25690 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e  described below.
256a0 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20 63    After a type c
256b0 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68  onversion,.** th
256c0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
256d0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
256e0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64  mn_type() is und
256f0 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a  efined.  Future.
25700 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ** versions of S
25710 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65  QLite may change
25720 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66   the behavior of
25730 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
25740 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77  type().** follow
25750 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ing a type conve
25760 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rsion..**.** ^If
25770 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
25780 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73   BLOB or UTF-8 s
25790 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73  tring then the s
257a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
257b0 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  tes().** routine
257c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
257d0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
257e0 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
257f0 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
25800 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
25810 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  16 string, then 
25820 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25830 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a  ytes() converts.
25840 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
25850 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20   UTF-8 and then 
25860 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
25870 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
25880 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
25890 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
258a0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
258b0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73  olumn_bytes() us
258c0 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
258d0 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
258e0 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
258f0 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69   to a UTF-8 stri
25900 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
25910 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
25920 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
25930 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
25940 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
25950 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
25960 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74  lumn_bytes() ret
25970 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
25980 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
25990 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
259a0 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20  -16 string then 
259b0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
259c0 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20  mn_bytes16().** 
259d0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
259e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
259f0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
25a00 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
25a10 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
25a20 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c   a UTF-8 string,
25a30 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
25a40 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63  lumn_bytes16() c
25a50 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
25a60 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20  tring to UTF-16 
25a70 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
25a80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
25a90 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
25aa0 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
25ab0 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
25ac0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
25ad0 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a  ytes16() uses.**
25ae0 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
25af0 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74  tf()] to convert
25b00 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61   that value to a
25b10 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61   UTF-16 string a
25b20 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
25b30 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
25b40 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
25b50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
25b60 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
25b70 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
25b80 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75 72  _bytes16() retur
25b90 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
25ba0 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
25bb0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
25bc0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20  column_bytes()] 
25bd0 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
25be0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
25bf0 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64  )] do not includ
25c00 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  e the zero termi
25c10 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e  nators at the en
25c20 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69  d.** of the stri
25c30 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74  ng.  ^For clarit
25c40 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72 65  y: the values re
25c50 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
25c60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
25c70 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  es()] and [sqlit
25c80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
25c90 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d  6()] are the num
25ca0 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20  ber of.** bytes 
25cb0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e  in the string, n
25cc0 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ot the number of
25cd0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
25ce0 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75  ** ^Strings retu
25cf0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
25d00 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e  column_text() an
25d10 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
25d20 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76  _text16(),.** ev
25d30 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73  en empty strings
25d40 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72  , are always zer
25d50 6f 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o terminated.  ^
25d60 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  The return.** va
25d70 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
25d80 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
25d90 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  or a zero-length
25da0 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20   BLOB is a NULL 
25db0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
25dc0 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72  The object retur
25dd0 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
25de0 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
25df0 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  is an.** [unprot
25e00 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
25e10 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e  lue] object.  An
25e20 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
25e30 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
25e40 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65  t.** may only be
25e50 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69   used with [sqli
25e60 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
25e70 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
25e80 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a  esult_value()]..
25e90 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f  ** If the [unpro
25ea0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
25eb0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74  alue] object ret
25ec0 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
25ed0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
25ee0 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20  e()] is used in 
25ef0 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69  any other way, i
25f00 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a  ncluding calls.*
25f10 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69  * to routines li
25f20 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ke [sqlite3_valu
25f30 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74  e_int()], [sqlit
25f40 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
25f50 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
25f60 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
25f70 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
25f80 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
25f90 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
25fa0 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f  tines attempt to
25fb0 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
25fc0 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70 72  ue where appropr
25fd0 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65  iate.  ^For.** e
25fe0 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69  xample, if the i
25ff0 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e  nternal represen
26000 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20  tation is FLOAT 
26010 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75 6c  and a text resul
26020 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65  t.** is requeste
26030 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  d, [sqlite3_snpr
26040 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64 20  intf()] is used 
26050 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65  internally to pe
26060 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e  rform the.** con
26070 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69  version automati
26080 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f  cally.  ^(The fo
26090 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65  llowing table de
260a0 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72  tails the conver
260b0 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72  sions.** that ar
260c0 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a  e applied:.**.**
260d0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a   <blockquote>.**
260e0 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
260f0 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
26100 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65  Internal<br>Type
26110 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c   <th> Requested<
26120 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f  br>Type <th>  Co
26130 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c  nversion.**.** <
26140 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
26150 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
26160 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30  <td> Result is 0
26170 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
26180 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  LL    <td>  FLOA
26190 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
261a0 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c   is 0.0.** <tr><
261b0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
261c0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
261d0 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
261e0 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
261f0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
26200 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
26210 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20   Result is NULL 
26220 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c  pointer.** <tr><
26230 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
26240 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
26250 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e   Convert from in
26260 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a  teger to float.*
26270 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
26280 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  ER  <td>   TEXT 
26290 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
262a0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69  ndering of the i
262b0 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74  nteger.** <tr><t
262c0 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e  d> INTEGER  <td>
262d0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
262e0 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d  Same as INTEGER-
262f0 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
26300 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
26310 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43  INTEGER   <td> C
26320 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61  onvert from floa
26330 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20  t to integer.** 
26340 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
26350 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
26360 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
26370 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
26380 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
26390 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
263a0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
263b0 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a   as FLOAT->TEXT.
263c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
263d0 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  T    <td> INTEGE
263e0 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f  R   <td> Use ato
263f0 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
26400 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
26410 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65  LOAT    <td> Use
26420 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atof().** <tr><
26430 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
26440 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
26450 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74   No change.** <t
26460 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
26470 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
26480 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
26490 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
264a0 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  i().** <tr><td> 
264b0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46   BLOB    <td>  F
264c0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
264d0 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
264e0 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20  n use atof().** 
264f0 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
26500 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
26510 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f   <td> Add a zero
26520 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e   terminator if n
26530 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65  eeded.** </table
26540 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74  >.** </blockquot
26550 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  e>)^.**.** The t
26560 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73  able above makes
26570 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74   reference to st
26580 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
26590 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28   functions atoi(
265a0 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e  ).** and atof().
265b0 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f    SQLite does no
265c0 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65  t really use the
265d0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49  se functions.  I
265e0 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e  t has its.** own
265f0 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65   equivalent inte
26600 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20  rnal routines.  
26610 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61  The atoi() and a
26620 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a  tof() names are.
26630 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20 74  ** used in the t
26640 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79  able for brevity
26650 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68 65   and because the
26660 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74  y are familiar t
26670 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67  o most.** C prog
26680 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e  rammers..**.** N
26690 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74 79  ote that when ty
266a0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f  pe conversions o
266b0 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72  ccur, pointers r
266c0 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72  eturned by prior
266d0 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  .** calls to sql
266e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
266f0 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  (), sqlite3_colu
26700 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f  mn_text(), and/o
26710 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
26720 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79  umn_text16() may
26730 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e   be invalidated.
26740 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73  .** Type convers
26750 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72  ions and pointer
26760 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d   invalidations m
26770 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ight occur.** in
26780 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
26790 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ases:.**.** <ul>
267a0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
267b0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
267c0 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74  a BLOB and sqlit
267d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
267e0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
267f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
26800 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
26810 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  A zero-terminato
26820 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20  r might.**      
26830 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65 64  need to be added
26840 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c   to the string.<
26850 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
26860 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
26870 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20 61   is UTF-8 text a
26880 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
26890 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a  n_bytes16() or.*
268a0 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
268b0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69  olumn_text16() i
268c0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
268d0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
268e0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
268f0 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e   to UTF-16.</li>
26900 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
26910 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
26920 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20  UTF-16 text and 
26930 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
26940 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20  ytes() or.**    
26950 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
26960 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65  _text() is calle
26970 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
26980 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
26990 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
269a0 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  -8.</li>.** </ul
269b0 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73  >.**.** ^Convers
269c0 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46  ions between UTF
269d0 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36  -16be and UTF-16
269e0 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f  le are always do
269f0 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20  ne in place and 
26a00 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69  do.** not invali
26a10 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69  date a prior poi
26a20 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20  nter, though of 
26a30 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65  course the conte
26a40 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  nt of the buffer
26a50 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72 69  .** that the pri
26a60 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72  or pointer refer
26a70 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20  ences will have 
26a80 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20  been modified.  
26a90 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f  Other kinds.** o
26aa0 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65  f conversion are
26ab0 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77   done in place w
26ac0 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62  hen it is possib
26ad0 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65  le, but sometime
26ae0 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f  s they.** are no
26af0 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69  t possible and i
26b00 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70 72  n those cases pr
26b10 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65  ior pointers are
26b20 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
26b30 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20 61  .** The safest a
26b40 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72 65  nd easiest to re
26b50 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73  member policy is
26b60 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65   to invoke these
26b70 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20   routines.** in 
26b80 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
26b90 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  wing ways:.**.**
26ba0 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71   <ul>.**  <li>sq
26bb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
26bc0 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  t() followed by 
26bd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
26be0 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20  ytes()</li>.**  
26bf0 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
26c00 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77  mn_blob() follow
26c10 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
26c20 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
26c30 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
26c40 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
26c50 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
26c60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
26c70 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c  es16()</li>.** <
26c80 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74  /ul>.**.** In ot
26c90 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73  her words, you s
26ca0 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74  hould call sqlit
26cb0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
26cc0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ,.** sqlite3_col
26cd0 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73  umn_blob(), or s
26ce0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
26cf0 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f 20  xt16() first to 
26d00 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c 74  force the result
26d10 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73  .** into the des
26d20 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65  ired format, the
26d30 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  n invoke sqlite3
26d40 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
26d50 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
26d60 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74  lumn_bytes16() t
26d70 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20  o find the size 
26d80 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20  of the result.  
26d90 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73  Do not mix calls
26da0 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  .** to sqlite3_c
26db0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20  olumn_text() or 
26dc0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
26dd0 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73  lob() with calls
26de0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
26df0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c  olumn_bytes16(),
26e00 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20   and do not mix 
26e10 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
26e20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
26e30 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74  .** with calls t
26e40 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
26e50 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20  _bytes()..**.** 
26e60 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65  ^The pointers re
26e70 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64  turned are valid
26e80 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f   until a type co
26e90 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20  nversion occurs 
26ea0 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20  as.** described 
26eb0 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20  above, or until 
26ec0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26ed0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
26ee0 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
26ef0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
26f00 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68   is called.  ^Th
26f10 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75  e memory space u
26f20 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69  sed to hold stri
26f30 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73  ngs.** and BLOBs
26f40 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61   is freed automa
26f50 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e  tically.  Do <b>
26f60 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65  not</b> pass the
26f70 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
26f80 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ed.** [sqlite3_c
26f90 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b  olumn_blob()], [
26fa0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
26fb0 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74  ext()], etc. int
26fc0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  o.** [sqlite3_fr
26fd0 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  ee()]..**.** ^(I
26fe0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
26ff0 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75  ation error occu
27000 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65 76  rs during the ev
27010 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a  aluation of any.
27020 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ** of these rout
27030 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20  ines, a default 
27040 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65  value is returne
27050 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20  d.  The default 
27060 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68  value.** is eith
27070 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20 30  er the integer 0
27080 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70  , the floating p
27090 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c  oint number 0.0,
270a0 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f   or a NULL.** po
270b0 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75 65  inter.  Subseque
270c0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
270d0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
270e0 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  will return.** [
270f0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e  SQLITE_NOMEM].)^
27100 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
27110 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
27120 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73  e3_column_blob(s
27130 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27140 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
27150 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
27160 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c  column_bytes(sql
27170 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
27180 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
27190 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
271a0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c  lumn_bytes16(sql
271b0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
271c0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
271d0 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  I double sqlite3
271e0 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
271f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27200 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
27210 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
27220 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
27230 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
27240 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
27250 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
27260 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
27270 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
27280 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
27290 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e  ITE_API const un
272a0 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
272b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
272c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
272d0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
272e0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
272f0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27300 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
27310 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
27320 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
27330 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27340 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  type(sqlite3_stm
27350 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
27360 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
27370 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
27380 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
27390 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
273a0 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
273b0 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
273c0 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
273d0 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
273e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
273f0 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
27400 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
27410 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
27420 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
27430 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
27440 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
27450 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
27460 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e  nt encountered n
27470 6f 20 65 72 72 6f 72 73 20 6f 72 0a 2a 2a 20 6f  o errors or.** o
27480 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
27490 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
274a0 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
274b0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
274c0 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
274d0 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
274e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
274f0 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
27500 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
27510 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
27520 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
27530 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
27540 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
27550 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
27560 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
27570 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
27580 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
27590 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
275a0 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
275b0 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
275c0 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
275d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
275e0 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
275f0 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
27600 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
27610 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
27620 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
27630 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
27640 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
27650 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
27660 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
27670 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
27680 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
27690 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
276a0 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
276b0 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
276c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
276d0 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
276e0 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
276f0 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
27700 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
27710 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
27720 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
27730 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
27740 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
27750 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
27760 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
27770 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
27780 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
27790 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
277a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
277b0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
277c0 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
277d0 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
277e0 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
277f0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
27800 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
27810 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
27820 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
27830 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
27840 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
27850 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
27860 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ption..*/.SQLITE
27870 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
27880 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
27890 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
278a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
278b0 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
278c0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
278d0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
278e0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
278f0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
27900 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
27910 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
27920 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
27930 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
27940 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
27950 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
27960 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
27970 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
27980 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
27990 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
279a0 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
279b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
279c0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
279d0 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
279e0 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
279f0 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
27a00 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
27a10 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
27a20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
27a30 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
27a40 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
27a50 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
27a60 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
27a70 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
27a80 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
27a90 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
27aa0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
27ab0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
27ac0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
27ad0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
27ae0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
27af0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
27b00 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
27b10 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
27b20 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
27b30 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
27b40 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
27b50 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
27b60 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
27b70 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
27b80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
27b90 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
27ba0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
27bb0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
27bc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27bd0 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
27be0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
27bf0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
27c00 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
27c10 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
27c20 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
27c30 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
27c40 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
27c50 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
27c60 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
27c70 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
27c80 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
27c90 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
27ca0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27cb0 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50   S..*/.SQLITE_AP
27cc0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  I int sqlite3_re
27cd0 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
27ce0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
27cf0 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
27d00 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
27d10 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
27d20 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
27d30 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
27d40 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
27d50 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
27d60 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
27d70 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
27d80 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
27d90 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
27da0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
27db0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
27dc0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
27dd0 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
27de0 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
27df0 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
27e00 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
27e10 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
27e20 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
27e30 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
27e40 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
27e50 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
27e60 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
27e70 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
27e80 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
27e90 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
27ea0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
27eb0 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
27ec0 74 68 65 20 74 68 65 20 73 65 63 6f 6e 64 20 70  the the second p
27ed0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61  arameter (the na
27ee0 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  me of the functi
27ef0 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  on being created
27f00 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65  ).** and the pre
27f10 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65  sence or absence
27f20 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72   of a destructor
27f30 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a   callback for.**
27f40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
27f50 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a   data pointer..*
27f60 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
27f70 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
27f80 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
27f90 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
27fa0 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
27fb0 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
27fc0 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c  ed.  ^If an appl
27fd0 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72  ication uses mor
27fe0 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
27ff0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
28000 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69  n then applicati
28010 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
28020 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
28030 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63   added.** to eac
28040 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
28050 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79  ction separately
28060 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
28070 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
28080 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
28090 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
280a0 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
280b0 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54  * redefined.  ^T
280c0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
280d0 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
280e0 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e   to 255 bytes in
280f0 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72   a UTF-8.** repr
28100 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c  esentation, excl
28110 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
28120 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  o-terminator.  ^
28130 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
28140 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d  me.** length lim
28150 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62  it is in UTF-8 b
28160 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63  ytes, not charac
28170 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20  ters nor UTF-16 
28180 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79  bytes.  .** ^Any
28190 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
281a0 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
281b0 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
281c0 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
281d0 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  in [SQLITE_MISUS
281e0 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  E] being returne
281f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  d..**.** ^The th
28200 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
28210 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
28220 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
28230 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
28240 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
28250 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
28260 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74  ^If this paramet
28270 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74  er is -1, then t
28280 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
28290 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
282a0 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
282b0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
282c0 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
282d0 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20  he limit.** set 
282e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
282f0 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
28300 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e  _FUNCTION_ARG]).
28310 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a    If the third.*
28320 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  * parameter is l
28330 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67  ess than -1 or g
28340 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20  reater than 127 
28350 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
28360 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
28370 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
28380 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
28390 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
283a0 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
283b0 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
283c0 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
283d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
283e0 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
283f0 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72  arameters.  Ever
28400 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
28410 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
28420 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  st be able to wo
28430 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38  rk.** with UTF-8
28440 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
28450 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
28460 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
28470 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
28480 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
28490 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
284a0 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e  an another.  ^An
284b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
284c0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
284d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
284e0 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
284f0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
28500 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  6() multiple.** 
28510 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
28520 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74  ame function but
28530 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
28540 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52  values of eTextR
28550 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c  ep..** ^When mul
28560 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
28570 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
28580 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
28590 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
285a0 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
285b0 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
285c0 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
285d0 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
285e0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74  version..** If t
285f0 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73  here is only a s
28600 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ingle implementa
28610 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20  tion which does 
28620 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65  not care what te
28630 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69  xt.** encoding i
28640 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  s used, then the
28650 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
28660 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49   should be [SQLI
28670 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  TE_ANY]..**.** ^
28680 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
28690 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
286a0 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
286b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
286c0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
286d0 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
286e0 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
286f0 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
28700 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
28710 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
28720 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
28730 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
28740 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
28750 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
28760 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
28770 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
28780 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
28790 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
287a0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
287b0 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
287c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
287d0 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
287e0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
287f0 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
28800 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
28810 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
28820 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
28830 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
28840 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
28850 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
28860 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
28870 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
28880 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
28890 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
288a0 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
288b0 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
288c0 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
288d0 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
288e0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
288f0 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
28900 4c 4c 20 70 6f 69 6e 65 72 73 20 66 6f 72 20 61  LL poiners for a
28910 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
28920 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
28930 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
28940 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
28950 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
28960 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
28970 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
28980 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
28990 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
289a0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
289b0 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
289c0 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
289d0 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
289e0 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
289f0 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
28a00 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
28a10 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
28a20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28a30 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
28a40 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
28a50 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
28a60 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
28a70 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
28a80 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
28a90 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
28aa0 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
28ab0 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
28ac0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
28ad0 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
28ae0 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
28af0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
28b00 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
28b10 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
28b20 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
28b30 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
28b40 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
28b50 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
28b60 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
28b70 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
28b80 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
28b90 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
28ba0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
28bb0 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
28bc0 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
28bd0 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
28be0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
28bf0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
28c00 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
28c10 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
28c20 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
28c30 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
28c40 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
28c50 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
28c60 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
28c70 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
28c80 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
28c90 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
28ca0 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
28cb0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
28cc0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
28cd0 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
28ce0 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
28cf0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
28d00 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
28d10 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
28d20 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
28d30 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
28d40 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
28d50 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
28d60 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
28d70 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
28d80 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
28d90 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
28da0 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
28db0 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
28dc0 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
28dd0 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
28de0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
28df0 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
28e00 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
28e10 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
28e20 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
28e30 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
28e40 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
28e50 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
28e60 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
28e70 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
28e80 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
28e90 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
28ea0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
28eb0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
28ec0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
28ed0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
28ee0 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
28ef0 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
28f00 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
28f10 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
28f20 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
28f30 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
28f40 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
28f50 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
28f60 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
28f70 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
28f80 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
28f90 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
28fa0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
28fb0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28fc0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
28fd0 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
28fe0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
28ff0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
29000 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
29010 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
29020 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
29030 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
29040 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
29050 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
29060 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
29070 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
29080 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
29090 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
290a0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
290b0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53  3_context*).);.S
290c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
290d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
290e0 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
290f0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
29100 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
29110 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
29120 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
29130 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
29140 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
29150 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
29160 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
29170 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
29180 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
29190 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
291a0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
291b0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
291c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
291d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
291e0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
291f0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
29200 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
29210 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
29220 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
29230 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
29240 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
29250 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
29260 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
29270 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
29280 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
29290 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
292a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
292b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
292c0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
292d0 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
292e0 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
292f0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
29300 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29310 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
29320 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
29330 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
29340 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
29350 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
29360 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
29370 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
29380 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
29390 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
293a0 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
293b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
293c0 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
293d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
293e0 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
293f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29400 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
29410 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
29420 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
29430 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
29440 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
29450 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
29460 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e  eate_function on
29470 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
29480 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
29490 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
294a0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
294b0 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
294c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
294d0 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
294e0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
294f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
29500 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
29510 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
29520 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
29530 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
29540 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
29550 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
29560 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
29570 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
29580 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
29590 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
295a0 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
295b0 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
295c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
295d0 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
295e0 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
295f0 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
29600 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
29610 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
29620 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74   tell you what t
29630 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
29640 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
29650 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
29660 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
29670 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
29680 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
29690 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
296a0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
296b0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
296c0 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
296d0 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
296e0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
296f0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
29700 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
29710 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
29720 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
29730 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
29740 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
29750 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
29760 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
29770 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
29780 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
29790 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
297a0 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
297b0 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
297c0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
297d0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
297e0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
297f0 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
29800 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
29810 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c  4,int),void*,sql
29820 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
29830 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
29840 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
29850 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
29860 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
29870 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
29880 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
29890 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
298a0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
298b0 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
298c0 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
298d0 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
298e0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
298f0 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
29900 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
29910 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
29920 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
29930 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
29940 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
29950 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
29960 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
29970 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
29980 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
29990 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
299a0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
299b0 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
299c0 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
299d0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
299e0 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
299f0 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
29a00 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
29a10 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
29a20 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
29a30 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
29a40 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
29a50 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
29a60 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
29a70 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
29a80 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
29a90 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
29aa0 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
29ab0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
29ac0 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
29ad0 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
29ae0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
29af0 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
29b00 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
29b10 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
29b20 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29b30 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
29b40 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
29b50 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
29b60 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
29b70 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
29b80 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
29b90 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
29ba0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
29bb0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
29bc0 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
29bd0 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
29be0 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
29bf0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
29c00 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
29c10 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
29c20 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
29c30 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
29c40 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
29c50 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
29c60 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
29c70 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
29c80 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
29c90 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
29ca0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
29cb0 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
29cc0 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
29cd0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
29ce0 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
29cf0 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
29d00 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
29d10 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
29d20 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
29d30 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
29d40 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
29d50 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
29d60 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
29d70 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
29d80 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
29d90 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
29da0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
29db0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
29dc0 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
29dd0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
29de0 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
29df0 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
29e00 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
29e10 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
29e20 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
29e30 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
29e40 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
29e50 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
29e60 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
29e70 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
29e80 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
29e90 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
29ea0 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
29eb0 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
29ec0 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
29ed0 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
29ee0 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
29ef0 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
29f00 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
29f10 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
29f20 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
29f30 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
29f40 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
29f50 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
29f60 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
29f70 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
29f80 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
29f90 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
29fa0 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
29fb0 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
29fc0 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
29fd0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
29fe0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
29ff0 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
2a000 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2a010 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
2a020 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
2a030 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
2a040 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2a050 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
2a060 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2a070 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
2a080 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2a090 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
2a0a0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2a0b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
2a0c0 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
2a0d0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2a0e0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
2a0f0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
2a100 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
2a110 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
2a120 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
2a130 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
2a140 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2a150 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
2a160 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2a170 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2a180 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2a190 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
2a1a0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2a1b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2a1c0 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
2a1d0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2a1e0 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c  E_API double sql
2a1f0 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
2a200 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2a210 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2a220 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2a230 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
2a240 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2a250 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
2a260 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
2a270 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
2a280 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2a290 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
2a2a0 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
2a2b0 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
2a2c0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
2a2d0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2a2e0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2a2f0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
2a300 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
2a310 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2a320 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2a330 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2a340 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2a350 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2a360 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
2a370 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2a380 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2a390 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
2a3a0 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
2a3b0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
2a3c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2a3d0 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
2a3e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2a3f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a400 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
2a410 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
2a420 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
2a430 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
2a440 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2a450 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
2a460 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
2a470 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
2a480 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
2a490 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
2a4a0 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
2a4b0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2a4c0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
2a4d0 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
2a4e0 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
2a4f0 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
2a500 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
2a510 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
2a520 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
2a530 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
2a540 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2a550 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2a560 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
2a570 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2a580 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
2a590 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
2a5a0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
2a5b0 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
2a5c0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
2a5d0 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
2a5e0 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
2a5f0 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
2a600 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2a610 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
2a620 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
2a630 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
2a640 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
2a650 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
2a660 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
2a670 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
2a680 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
2a690 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
2a6a0 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
2a6b0 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
2a6c0 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
2a6d0 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
2a6e0 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
2a6f0 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
2a700 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
2a710 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
2a720 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
2a730 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
2a740 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
2a750 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2a760 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
2a770 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
2a780 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
2a790 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
2a7a0 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
2a7b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
2a7c0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2a7d0 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
2a7e0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
2a7f0 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65  er if N is.** le
2a800 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
2a810 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
2a820 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
2a830 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
2a840 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
2a850 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
2a860 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
2a870 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2a880 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
2a890 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
2a8a0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
2a8b0 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
2a8c0 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
2a8d0 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
2a8e0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
2a8f0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
2a900 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2a910 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
2a920 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
2a930 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
2a940 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
2a950 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
2a960 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  allocation.)^.**
2a970 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
2a980 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
2a990 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
2a9a0 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
2a9b0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2a9c0 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
2a9d0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
2a9e0 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
2a9f0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
2aa00 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
2aa10 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
2aa20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2aa30 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
2aa40 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
2aa50 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
2aa60 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
2aa70 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
2aa80 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
2aa90 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2aaa0 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
2aab0 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2aac0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
2aad0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2aae0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2aaf0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2ab00 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2ab10 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2ab20 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
2ab30 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
2ab40 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2ab50 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
2ab60 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
2ab70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ab80 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
2ab90 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
2aba0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
2abb0 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
2abc0 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
2abd0 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
2abe0 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
2abf0 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
2ac00 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
2ac10 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
2ac20 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2ac30 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
2ac40 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2ac50 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2ac60 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
2ac70 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
2ac80 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
2ac90 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2aca0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
2acb0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2acc0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2acd0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2ace0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2acf0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2ad00 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2ad10 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
2ad20 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
2ad30 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
2ad40 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
2ad50 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
2ad60 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
2ad70 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
2ad80 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
2ad90 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
2ada0 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
2adb0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2adc0 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
2add0 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
2ade0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
2adf0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
2ae00 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
2ae10 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
2ae20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2ae30 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
2ae40 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2ae50 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
2ae60 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
2ae70 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
2ae80 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
2ae90 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
2aea0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
2aeb0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
2aec0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
2aed0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2aee0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
2aef0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
2af00 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
2af10 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
2af20 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
2af30 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
2af40 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
2af50 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
2af60 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
2af70 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
2af80 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
2af90 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
2afa0 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
2afb0 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
2afc0 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
2afd0 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
2afe0 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
2aff0 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
2b000 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
2b010 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
2b020 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
2b030 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
2b040 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
2b050 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
2b060 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
2b070 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
2b080 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
2b090 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
2b0a0 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
2b0b0 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
2b0c0 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
2b0d0 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
2b0e0 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
2b0f0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
2b100 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
2b110 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
2b120 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
2b130 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
2b140 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
2b150 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
2b160 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
2b170 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
2b180 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
2b190 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
2b1a0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
2b1b0 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
2b1c0 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
2b1d0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
2b1e0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
2b1f0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
2b200 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
2b210 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
2b220 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
2b230 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
2b240 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
2b250 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
2b260 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
2b270 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
2b280 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2b290 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
2b2a0 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
2b2b0 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
2b2c0 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
2b2d0 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
2b2e0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
2b2f0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
2b300 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
2b310 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
2b320 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
2b330 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
2b340 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
2b350 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
2b360 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
2b370 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
2b380 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
2b390 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
2b3a0 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
2b3b0 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
2b3c0 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
2b3d0 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
2b3e0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
2b3f0 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
2b400 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
2b410 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2b420 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
2b430 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
2b440 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2b450 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
2b460 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
2b470 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
2b480 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
2b490 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20  * ^If it is not 
2b4a0 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
2b4b0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
2b4c0 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
2b4d0 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
2b4e0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
2b4f0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
2b500 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
2b510 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
2b520 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2b530 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
2b540 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
2b550 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
2b560 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
2b570 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
2b580 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
2b590 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
2b5a0 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
2b5b0 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
2b5c0 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
2b5d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
2b5e0 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
2b5f0 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65   any time.  ^The
2b600 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
2b610 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
2b620 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
2b630 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
2b640 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
2b650 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  dropped..**.** ^
2b660 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
2b670 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
2b680 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
2b690 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
2b6a0 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
2b6b0 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
2b6c0 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
2b6d0 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
2b6e0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
2b6f0 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
2b700 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].)^.**.** These
2b710 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
2b720 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
2b730 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
2b740 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
2b750 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2b760 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
2b770 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
2b780 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
2b790 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2b7a0 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
2b7b0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
2b7c0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
2b7d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
2b7e0 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
2b7f0 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
2b800 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b810 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
2b820 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
2b830 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
2b840 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
2b850 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
2b860 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
2b870 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
2b880 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
2b890 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
2b8a0 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
2b8b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
2b8c0 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
2b8d0 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
2b8e0 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
2b8f0 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
2b900 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
2b910 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
2b920 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
2b930 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
2b940 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
2b950 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
2b960 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
2b970 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
2b980 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
2b990 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
2b9a0 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
2b9b0 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
2b9c0 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
2b9d0 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
2b9e0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
2b9f0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
2ba00 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
2ba10 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
2ba20 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
2ba30 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
2ba40 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
2ba50 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
2ba60 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
2ba70 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
2ba80 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
2ba90 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
2baa0 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
2bab0 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
2bac0 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
2bad0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2bae0 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
2baf0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
2bb00 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
2bb10 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2bb20 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
2bb30 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
2bb40 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
2bb50 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
2bb60 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2bb70 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
2bb80 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
2bb90 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
2bba0 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
2bbb0 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
2bbc0 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
2bbd0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
2bbe0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
2bbf0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2bc00 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
2bc10 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
2bc20 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
2bc30 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2bc40 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
2bc50 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
2bc60 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
2bc70 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
2bc80 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
2bc90 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
2bca0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
2bcb0 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
2bcc0 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
2bcd0 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
2bce0 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
2bcf0 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
2bd00 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
2bd10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2bd20 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
2bd30 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2bd40 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
2bd50 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
2bd60 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2bd70 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
2bd80 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
2bd90 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
2bda0 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
2bdb0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
2bdc0 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
2bdd0 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
2bde0 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
2bdf0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
2be00 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2be10 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
2be20 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
2be30 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
2be40 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2be50 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2be60 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
2be70 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
2be80 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
2be90 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
2bea0 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
2beb0 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
2bec0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
2bed0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2bee0 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
2bef0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2bf00 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
2bf10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2bf20 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2bf30 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
2bf40 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
2bf50 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
2bf60 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
2bf70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2bf80 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
2bf90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2bfa0 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
2bfb0 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
2bfc0 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
2bfd0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
2bfe0 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
2bff0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
2c000 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
2c010 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
2c020 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
2c030 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
2c040 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
2c050 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2c060 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
2c070 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
2c080 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
2c090 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
2c0a0 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2c0b0 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
2c0c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2c0d0 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
2c0e0 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
2c0f0 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
2c100 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
2c110 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
2c120 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
2c130 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
2c140 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
2c150 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2c160 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2c170 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
2c180 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2c190 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
2c1a0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
2c1b0 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
2c1c0 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
2c1d0 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
2c1e0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
2c1f0 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
2c200 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2c210 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
2c220 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
2c230 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
2c240 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
2c250 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
2c260 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
2c270 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
2c280 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
2c290 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
2c2a0 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
2c2b0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
2c2c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2c2d0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
2c2e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2c2f0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
2c300 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
2c310 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
2c320 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
2c330 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
2c340 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
2c350 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
2c360 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
2c370 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
2c380 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
2c390 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
2c3a0 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
2c3b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2c3c0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
2c3d0 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
2c3e0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
2c3f0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2c400 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
2c410 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
2c420 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
2c430 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
2c440 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
2c450 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
2c460 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
2c470 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
2c480 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
2c490 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2c4a0 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
2c4b0 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
2c4c0 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
2c4d0 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
2c4e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 6f 6f  lite3_result_too
2c4f0 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
2c500 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
2c510 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
2c520 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
2c530 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
2c540 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
2c550 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
2c560 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c570 5f 72 65 73 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20  _result_nomem() 
2c580 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
2c590 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77   SQLite to throw
2c5a0 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64   an error.** ind
2c5b0 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d  icating that a m
2c5c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
2c5d0 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   failed..**.** ^
2c5e0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2c5f0 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61  lt_int() interfa
2c600 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2c610 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2c620 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2c630 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2c640 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74  to be the 32-bit
2c650 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2c660 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
2c670 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
2c680 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  nt..** ^The sqli
2c690 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34  te3_result_int64
2c6a0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2c6b0 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
2c6c0 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
2c6d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2c6e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2c6f0 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65  the 64-bit signe
2c700 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
2c710 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
2c720 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
2c730 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2c740 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69  _result_null() i
2c750 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2c760 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2c770 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
2c780 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2c790 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c  ction to be NULL
2c7a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2c7b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2c7c0 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  (), sqlite3_resu
2c7d0 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  lt_text16(),.** 
2c7e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2c7f0 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73  ext16le(), and s
2c800 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2c810 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61  xt16be() interfa
2c820 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72  ces.** set the r
2c830 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
2c840 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2c850 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2c860 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20  to be.** a text 
2c870 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20  string which is 
2c880 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55  represented as U
2c890 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74  TF-8, UTF-16 nat
2c8a0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a  ive byte order,.
2c8b0 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65  ** UTF-16 little
2c8c0 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d   endian, or UTF-
2c8d0 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72  16 big endian, r
2c8e0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2c8f0 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68  ^SQLite takes th
2c900 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72  e text result fr
2c910 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  om the applicati
2c920 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32  on from.** the 2
2c930 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
2c940 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2c950 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2c960 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ces..** ^If the 
2c970 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
2c980 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2c990 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2c9a0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74  aces.** is negat
2c9b0 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ive, then SQLite
2c9c0 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65   takes result te
2c9d0 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20  xt from the 2nd 
2c9e0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72  parameter.** thr
2c9f0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
2ca00 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
2ca10 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
2ca20 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2ca30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2ca40 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2ca50 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  * is non-negativ
2ca60 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20  e, then as many 
2ca70 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
2ca80 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65  cters) of the te
2ca90 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  xt.** pointed to
2caa0 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
2cab0 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20  meter are taken 
2cac0 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  as the applicati
2cad0 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75  on-defined.** fu
2cae0 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 0a 2a  nction result..*
2caf0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
2cb00 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
2cb10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
2cb20 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
2cb30 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
2cb40 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f  ult_blob is a no
2cb50 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
2cb60 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c  then SQLite call
2cb70 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69  s that.** functi
2cb80 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75  on as the destru
2cb90 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74  ctor on the text
2cba0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
2cbb0 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66  when it has.** f
2cbc0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
2cbd0 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
2cbe0 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
2cbf0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2cc00 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2cc10 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f  interfaces or to
2cc20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
2cc30 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
2cc40 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
2cc50 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74  SQLITE_STATIC, t
2cc60 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73  hen SQLite.** as
2cc70 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74  sumes that the t
2cc80 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
2cc90 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e  lt is in constan
2cca0 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  t space and does
2ccb0 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65   not.** copy the
2ccc0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
2ccd0 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61  parameter nor ca
2cce0 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  ll a destructor 
2ccf0 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a  on the content.*
2cd00 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69  * when it has fi
2cd10 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
2cd20 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
2cd30 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
2cd40 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
2cd50 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2cd60 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20  nterfaces.** or 
2cd70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
2cd80 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69  lob is the speci
2cd90 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49  al constant SQLI
2cda0 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20  TE_TRANSIENT.** 
2cdb0 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65  then SQLite make
2cdc0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
2cdd0 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63  result into spac
2cde0 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a  e obtained from.
2cdf0 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
2ce00 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72  _malloc()] befor
2ce10 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  e it returns..**
2ce20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2ce30 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
2ce40 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2ce50 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20  he result of.** 
2ce60 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2ce70 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2ce80 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68   to be a copy th
2ce90 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  e.** [unprotecte
2cea0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2ceb0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
2cec0 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  d by the 2nd par
2ced0 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a  ameter.  ^The.**
2cee0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2cef0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
2cf00 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
2cf10 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
2cf20 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74  alue].** so that
2cf30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
2cf40 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69  lue] specified i
2cf50 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  n the parameter 
2cf60 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a  may change or.**
2cf70 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
2cf80 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65  after sqlite3_re
2cf90 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74  sult_value() ret
2cfa0 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72  urns without har
2cfb0 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63  m..** ^A [protec
2cfc0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2cfd0 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c  e] object may al
2cfe0 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65  ways be used whe
2cff0 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74  re an.** [unprot
2d000 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2d010 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72  lue] object is r
2d020 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68  equired, so eith
2d030 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73  er.** kind of [s
2d040 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2d050 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64  ject can be used
2d060 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72   with this inter
2d070 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  face..**.** If t
2d080 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2d090 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69  e called from wi
2d0a0 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65  thin the differe
2d0b0 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61  nt thread.** tha
2d0c0 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69  n the one contai
2d0d0 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61  ning the applica
2d0e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2d0f0 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69  ction that recei
2d100 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69  ved.** the [sqli
2d110 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69  te3_context] poi
2d120 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74  nter, the result
2d130 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2d140 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
2d150 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2d160 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  lt_blob(sqlite3_
2d170 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2d180 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2d190 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
2d1a0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
2d1b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
2d1c0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
2d1d0 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51  xt*, double);.SQ
2d1e0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
2d1f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2d200 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  or(sqlite3_conte
2d210 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
2d220 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
2d230 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
2d240 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73  result_error16(s
2d250 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2d260 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2d270 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
2d280 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2d290 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
2d2a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d2b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
2d2c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d2d0 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71  t_error_nomem(sq
2d2e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2d2f0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
2d300 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d310 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
2d320 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
2d330 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
2d340 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2d350 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
2d360 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51  ntext*, int);.SQ
2d370 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
2d380 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2d390 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
2d3a0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
2d3b0 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  64);.SQLITE_API 
2d3c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2d3d0 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33  ult_null(sqlite3
2d3e0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
2d3f0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
2d400 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
2d410 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2d420 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
2d430 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
2d440 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
2d450 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2d460 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74  ult_text16(sqlit
2d470 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2d480 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
2d490 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2d4a0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
2d4b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2d4c0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2d4d0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
2d4e0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
2d4f0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
2d500 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
2d510 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2d520 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
2d530 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
2d540 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
2d550 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
2d560 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
2d570 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c  result_value(sql
2d580 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
2d590 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2d5a0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
2d5b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
2d5c0 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2d5d0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29  context*, int n)
2d5e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d5f0 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f  F: Define New Co
2d600 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65  llating Sequence
2d610 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  s.**.** ^These f
2d620 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65  unctions add, re
2d630 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20  move, or modify 
2d640 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73  a [collation] as
2d650 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68  sociated.** with
2d660 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
2d670 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
2d680 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73  fied as the firs
2d690 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  t argument..**.*
2d6a0 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74  * ^The name of t
2d6b0 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  he collation is 
2d6c0 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  a UTF-8 string.*
2d6d0 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  * for sqlite3_cr
2d6e0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
2d6f0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65   and sqlite3_cre
2d700 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2d710 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d  ().** and a UTF-
2d720 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
2d730 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66  ive byte order f
2d740 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
2d750 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e  e_collation16().
2d760 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e  .** ^Collation n
2d770 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72  ames that compar
2d780 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e  e equal accordin
2d790 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  g to [sqlite3_st
2d7a0 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a  rnicmp()] are.**
2d7b0 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62   considered to b
2d7c0 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e  e the same name.
2d7d0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69  .**.** ^(The thi
2d7e0 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65  rd argument (eTe
2d7f0 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f  xtRep) must be o
2d800 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61  ne of the consta
2d810 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  nts:.** <ul>.** 
2d820 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
2d830 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8],.** <li> [SQL
2d840 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a  ITE_UTF16LE],.**
2d850 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
2d860 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16BE],.** <li> 
2d870 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20  [SQLITE_UTF16], 
2d880 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
2d890 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
2d8a0 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a  ]..** </ul>)^.**
2d8b0 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61   ^The eTextRep a
2d8c0 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e  rgument determin
2d8d0 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  es the encoding 
2d8e0 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65  of strings passe
2d8f0 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c  d.** to the coll
2d900 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
2d910 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61  allback, xCallba
2d920 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  ck..** ^The [SQL
2d930 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b  ITE_UTF16] and [
2d940 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
2d950 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72  GNED] values for
2d960 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72   eTextRep.** for
2d970 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65  ce strings to be
2d980 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69   UTF16 with nati
2d990 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
2d9a0 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55  * ^The [SQLITE_U
2d9b0 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
2d9c0 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70  lue for eTextRep
2d9d0 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20   forces strings 
2d9e0 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61  to begin.** on a
2d9f0 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72  n even byte addr
2da00 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ess..**.** ^The 
2da10 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
2da20 20 70 41 72 67 2c 20 69 73 20 61 20 61 70 70 6c   pArg, is a appl
2da30 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
2da40 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
2da50 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  sed.** through a
2da60 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
2da70 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c  ment to the coll
2da80 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
2da90 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
2daa0 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
2dab0 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69  nt, xCallback, i
2dac0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
2dad0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2dae0 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69  ction..** ^Multi
2daf0 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ple collating fu
2db00 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72  nctions can be r
2db10 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
2db20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
2db30 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72  t.** with differ
2db40 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72  ent eTextRep par
2db50 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69  ameters and SQLi
2db60 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63  te will use whic
2db70 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  hever.** functio
2db80 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c  n requires the l
2db90 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
2dba0 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69  ata transformati
2dbb0 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78  on..** ^If the x
2dbc0 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  Callback argumen
2dbd0 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  t is NULL then t
2dbe0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2dbf0 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65  ction is.** dele
2dc00 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20  ted.  ^When all 
2dc10 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2dc20 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73  ons having the s
2dc30 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c  ame name are del
2dc40 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f  eted,.** that co
2dc50 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f  llation is no lo
2dc60 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a  nger usable..**.
2dc70 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e  ** ^The collatin
2dc80 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
2dc90 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
2dca0 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ith a copy of th
2dcb0 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69  e pArg .** appli
2dcc0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2dcd0 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f  ter and with two
2dce0 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
2dcf0 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
2dd00 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65  ed.** by the eTe
2dd10 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20  xtRep argument. 
2dd20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
2dd30 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74  unction must ret
2dd40 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65  urn an.** intege
2dd50 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69  r that is negati
2dd60 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73  ve, zero, or pos
2dd70 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20  itive.** if the 
2dd80 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
2dd90 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c  less than, equal
2dda0 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
2ddb0 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c  than the second,
2ddc0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2ddd0 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  .  A collating f
2dde0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77  unction must alw
2ddf0 61 79 20 72 65 74 75 72 6e 20 74 68 65 20 73 61  ay return the sa
2de00 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76  me answer.** giv
2de10 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75  en the same inpu
2de20 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d  ts.  If two or m
2de30 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ore collating fu
2de40 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69  nctions are regi
2de50 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65  stered.** to the
2de60 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20   same collation 
2de70 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66  name (using diff
2de80 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76  erent eTextRep v
2de90 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a  alues) then all.
2dea0 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20  ** must give an 
2deb0 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65  equivalent answe
2dec0 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77  r when invoked w
2ded0 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73  ith equivalent s
2dee0 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63  trings..** The c
2def0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2df00 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20  n must obey the 
2df10 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72  following proper
2df20 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20  ties for all.** 
2df30 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e  strings A, B, an
2df40 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  d C:.**.** <ol>.
2df50 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
2df60 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c  then B==A..** <l
2df70 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42  i> If A==B and B
2df80 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a  ==C then A==C..*
2df90 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
2dfa0 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a   THEN B&gt;A..**
2dfb0 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
2dfc0 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20  and B&lt;C then 
2dfd0 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  A&lt;C..** </ol>
2dfe0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c  .**.** If a coll
2dff0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66  ating function f
2e000 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20  ails any of the 
2e010 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74  above constraint
2e020 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f  s and that.** co
2e030 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2e040 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20   is  registered 
2e050 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74  and used, then t
2e060 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53  he behavior of S
2e070 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65  QLite.** is unde
2e080 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2e090 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
2e0a0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
2e0b0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
2e0c0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e0d0 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68  ion().** with th
2e0e0 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20  e addition that 
2e0f0 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  the xDestroy cal
2e100 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
2e110 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a   on pArg when.**
2e120 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
2e130 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
2e140 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e  ed..** ^Collatin
2e150 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  g functions are 
2e160 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
2e170 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e  y are overridden
2e180 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c   by later.** cal
2e190 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  ls to the collat
2e1a0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e  ion creation fun
2e1b0 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74  ctions or when t
2e1c0 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
2e1d0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63  connection] is c
2e1e0 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  losed using [sql
2e1f0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a  ite3_close()]..*
2e200 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72  *.** ^The xDestr
2e210 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c  oy callback is <
2e220 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64  u>not</u> called
2e230 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69   if the .** sqli
2e240 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e250 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69  tion_v2() functi
2e260 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69  on fails.  Appli
2e270 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76  cations that inv
2e280 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  oke.** sqlite3_c
2e290 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
2e2a0 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d  v2() with a non-
2e2b0 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72  NULL xDestroy ar
2e2c0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a  gument should .*
2e2d0 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  * check the retu
2e2e0 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70  rn code and disp
2e2f0 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ose of the appli
2e300 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2e310 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65  ter.** themselve
2e320 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78  s rather than ex
2e330 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74  pecting SQLite t
2e340 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66  o deal with it f
2e350 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73  or them..** This
2e360 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72   is different fr
2e370 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53  om every other S
2e380 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
2e390 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65    The inconsiste
2e3a0 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72  ncy .** is unfor
2e3b0 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f  tunate but canno
2e3c0 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74  t be changed wit
2e3d0 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61  hout breaking ba
2e3e0 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70  ckwards .** comp
2e3f0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a  atibility..**.**
2e400 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c   See also:  [sql
2e410 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
2e420 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71  eeded()] and [sq
2e430 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2e440 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a  needed16()]..*/.
2e450 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2e460 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2e470 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
2e480 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
2e490 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
2e4a0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
2e4b0 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
2e4c0 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
2e4d0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2e4e0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
2e4f0 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *).);.SQLITE_API
2e500 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
2e510 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
2e520 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2e530 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
2e540 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74  me, .  int eText
2e550 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41  Rep, .  void *pA
2e560 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70  rg,.  int(*xComp
2e570 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  are)(void*,int,c
2e580 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63  onst void*,int,c
2e590 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76  onst void*),.  v
2e5a0 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76  oid(*xDestroy)(v
2e5b0 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  oid*).);.SQLITE_
2e5c0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2e5d0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2e5e0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  16(.  sqlite3*, 
2e5f0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a  .  const void *z
2e600 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78  Name,.  int eTex
2e610 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
2e620 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
2e630 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
2e640 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
2e650 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
2e660 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2e670 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65   Collation Neede
2e680 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  d Callbacks.**.*
2e690 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69  * ^To avoid havi
2e6a0 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20 61  ng to register a
2e6b0 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ll collation seq
2e6c0 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20  uences before a 
2e6d0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20  database.** can 
2e6e0 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c  be used, a singl
2e6f0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
2e700 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73  ion may be regis
2e710 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a  tered with the.*
2e720 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
2e730 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e  ection] to be in
2e740 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
2e750 6e 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c  n undefined coll
2e760 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
2e770 65 20 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a  e is required..*
2e780 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e  *.** ^If the fun
2e790 63 74 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65  ction is registe
2e7a0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 71  red using the sq
2e7b0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2e7c0 6e 65 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a  needed() API,.**
2e7d0 20 74 68 65 6e 20 69 74 20 69 73 20 70 61 73 73   then it is pass
2e7e0 65 64 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  ed the names of 
2e7f0 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
2e800 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73  ion sequences as
2e810 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f   strings.** enco
2e820 64 65 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49  ded in UTF-8. ^I
2e830 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  f sqlite3_collat
2e840 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69  ion_needed16() i
2e850 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e  s used,.** the n
2e860 61 6d 65 73 20 61 72 65 20 70 61 73 73 65 64 20  ames are passed 
2e870 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63  as UTF-16 in mac
2e880 68 69 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65  hine native byte
2e890 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61   order..** ^A ca
2e8a0 6c 6c 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e  ll to either fun
2e8b0 63 74 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74  ction replaces t
2e8c0 68 65 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c  he existing coll
2e8d0 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c  ation-needed cal
2e8e0 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57  lback..**.** ^(W
2e8f0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
2e900 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65   is invoked, the
2e910 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2e920 70 61 73 73 65 64 20 69 73 20 61 20 63 6f 70 79  passed is a copy
2e930 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  .** of the secon
2e940 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
2e950 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2e960 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73  needed() or.** s
2e970 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
2e980 5f 6e 65 65 64 65 64 31 36 28 29 2e 20 20 54 68  _needed16().  Th
2e990 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2e9a0 74 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73  t is the databas
2e9b0 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e  e.** connection.
2e9c0 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75    The third argu
2e9d0 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
2e9e0 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53  SQLITE_UTF8], [S
2e9f0 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
2ea00 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  ** or [SQLITE_UT
2ea10 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69  F16LE], indicati
2ea20 6e 67 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69  ng the most desi
2ea30 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68  rable form of th
2ea40 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  e collation.** s
2ea50 65 71 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e  equence function
2ea60 20 72 65 71 75 69 72 65 64 2e 20 20 54 68 65 20   required.  The 
2ea70 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2ea80 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
2ea90 74 68 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20  the.** required 
2eaa0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
2eab0 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ce.)^.**.** The 
2eac0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
2ead0 6e 20 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65  n should registe
2eae0 72 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f  r the desired co
2eaf0 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  llation using.**
2eb00 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2eb10 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b  _collation()], [
2eb20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2eb30 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f  ollation16()], o
2eb40 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  r.** [sqlite3_cr
2eb50 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
2eb60 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  2()]..*/.SQLITE_
2eb70 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2eb80 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
2eb90 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2eba0 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
2ebb0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
2ebc0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
2ebd0 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 53  onst char*).);.S
2ebe0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2ebf0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
2ec00 6e 65 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69  needed16(.  sqli
2ec10 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a  te3*, .  void*,.
2ec20 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c    void(*)(void*,
2ec30 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65  sqlite3*,int eTe
2ec40 78 74 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64  xtRep,const void
2ec50 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51  *).);..#ifdef SQ
2ec60 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f  LITE_HAS_CODEC./
2ec70 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
2ec80 20 6b 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72   key for an encr
2ec90 79 70 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  ypted database. 
2eca0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68   This routine sh
2ecb0 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65  ould be.** calle
2ecc0 64 20 72 69 67 68 74 20 61 66 74 65 72 20 73 71  d right after sq
2ecd0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a  lite3_open()..**
2ece0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
2ecf0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
2ed00 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
2ed10 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
2ed20 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
2ed30 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54  SQLite..*/.SQLIT
2ed40 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2ed50 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  3_key(.  sqlite3
2ed60 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2ed70 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2ed80 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
2ed90 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
2eda0 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
2edb0 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6b 65 79  y     /* The key
2edc0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68   */.);../*.** Ch
2edd0 61 6e 67 65 20 74 68 65 20 6b 65 79 20 6f 6e 20  ange the key on 
2ede0 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
2edf0 2e 20 20 49 66 20 74 68 65 20 63 75 72 72 65 6e  .  If the curren
2ee00 74 20 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f  t database is no
2ee10 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65 64 2c 20  t.** encrypted, 
2ee20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
2ee30 6c 20 65 6e 63 72 79 70 74 20 69 74 2e 20 20 49  l encrypt it.  I
2ee40 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65  f pNew==0 or nNe
2ee50 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74  w==0, the.** dat
2ee60 61 62 61 73 65 20 69 73 20 64 65 63 72 79 70 74  abase is decrypt
2ee70 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ed..**.** The co
2ee80 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
2ee90 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
2eea0 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
2eeb0 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
2eec0 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
2eed0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2eee0 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20  sqlite3_rekey(. 
2eef0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2ef00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2ef10 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2ef20 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2ef30 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2ef40 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2ef50 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a   The new key */.
2ef60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  );../*.** Specif
2ef70 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
2ef80 20 6b 65 79 20 66 6f 72 20 61 20 53 45 45 20 64   key for a SEE d
2ef90 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
2efa0 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
2efb0 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20  none of the SEE 
2efc0 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
2efd0 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  rk..*/.SQLITE_AP
2efe0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  I void sqlite3_a
2eff0 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20 20 63  ctivate_see(.  c
2f000 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
2f010 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
2f020 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
2f030 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
2f040 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 45  .#ifdef SQLITE_E
2f050 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a  NABLE_CEROD./*.*
2f060 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
2f070 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
2f080 20 61 20 43 45 52 4f 44 20 64 61 74 61 62 61 73   a CEROD databas
2f090 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61  e.  Unless .** a
2f0a0 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f  ctivated, none o
2f0b0 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f 75 74  f the CEROD rout
2f0c0 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a  ines will work..
2f0d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
2f0e0 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76  id sqlite3_activ
2f0f0 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e  ate_cerod(.  con
2f100 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68  st char *zPassPh
2f110 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41  rase        /* A
2f120 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65  ctivation phrase
2f130 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f   */.);.#endif../
2f140 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2f150 75 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e  uspend Execution
2f160 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d   For A Short Tim
2f170 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f180 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63  te3_sleep() func
2f190 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20  tion causes the 
2f1a0 63 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74  current thread t
2f1b0 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74  o suspend execut
2f1c0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65  ion.** for at le
2f1d0 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20  ast a number of 
2f1e0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65  milliseconds spe
2f1f0 63 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61  cified in its pa
2f200 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49  rameter..**.** I
2f210 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  f the operating 
2f220 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20  system does not 
2f230 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65  support sleep re
2f240 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d  quests with.** m
2f250 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20  illisecond time 
2f260 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e  resolution, then
2f270 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62   the time will b
2f280 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a  e rounded up to.
2f290 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73  ** the nearest s
2f2a0 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65  econd. The numbe
2f2b0 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
2f2c0 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61  s of sleep actua
2f2d0 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  lly.** requested
2f2e0 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74   from the operat
2f2f0 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65  ing system is re
2f300 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  turned..**.** ^S
2f310 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73  QLite implements
2f320 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
2f330 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78  by calling the x
2f340 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f  Sleep().** metho
2f350 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
2f360 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
2f370 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78  bject.  If the x
2f380 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a  Sleep() method.*
2f390 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  * of the default
2f3a0 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c   VFS is not impl
2f3b0 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c  emented correctl
2f3c0 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d  y, or not implem
2f3d0 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c  ented at.** all,
2f3e0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
2f3f0 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c  or of sqlite3_sl
2f400 65 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74  eep() may deviat
2f410 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72  e from the descr
2f420 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65  iption.** in the
2f430 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72   previous paragr
2f440 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  aphs..*/.SQLITE_
2f450 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2f460 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  sleep(int);../*.
2f470 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d  ** CAPI3REF: Nam
2f480 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72 20  e Of The Folder 
2f490 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72 61 72  Holding Temporar
2f4a0 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  y Files.**.** ^(
2f4b0 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
2f4c0 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
2f4d0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
2f4e0 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
2f4f0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
2f500 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
2f510 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
2f520 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ll temporary fil
2f530 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  es.** created by
2f540 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75 73 69   SQLite when usi
2f550 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73  ng a built-in [s
2f560 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
2f570 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61  ].** will be pla
2f580 63 65 64 20 69 6e 20 74 68 61 74 20 64 69 72 65  ced in that dire
2f590 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20 74 68  ctory.)^  ^If th
2f5a0 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69  is variable.** i
2f5b0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2f5c0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 70 65  , then SQLite pe
2f5d0 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63 68 20  rforms a search 
2f5e0 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72 69 61  for an appropria
2f5f0 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
2f600 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79 2e 0a  file directory..
2f610 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20  **.** It is not 
2f620 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
2f630 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
2f640 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20 74 68 61  able in more tha
2f650 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20  n one.** thread 
2f660 61 74 20 61 20 74 69 6d 65 2e 20 20 49 74 20 69  at a time.  It i
2f670 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
2f680 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
2f690 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66  s variable.** if
2f6a0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2f6b0 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
2f6c0 67 20 75 73 65 64 20 61 74 20 74 68 65 20 73 61  g used at the sa
2f6d0 6d 65 20 74 69 6d 65 20 69 6e 20 61 20 73 65 70  me time in a sep
2f6e0 61 72 61 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e  arate.** thread.
2f6f0 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74 65 6e 64  .** It is intend
2f700 65 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ed that this var
2f710 69 61 62 6c 65 20 62 65 20 73 65 74 20 6f 6e 63  iable be set onc
2f720 65 0a 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20  e.** as part of 
2f730 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69  process initiali
2f740 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72  zation and befor
2f750 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74  e any SQLite int
2f760 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e  erface.** routin
2f770 65 73 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  es have been cal
2f780 6c 65 64 20 61 6e 64 20 74 68 61 74 20 74 68 69  led and that thi
2f790 73 20 76 61 72 69 61 62 6c 65 20 72 65 6d 61 69  s variable remai
2f7a0 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74  n unchanged.** t
2f7b0 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a  hereafter..**.**
2f7c0 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72   ^The [temp_stor
2f7d0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2f7e0 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66 79 20 74  ma] may modify t
2f7f0 68 69 73 20 76 61 72 69 61 62 6c 65 20 61 6e 64  his variable and
2f800 20 63 61 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20   cause.** it to 
2f810 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
2f820 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
2f830 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20  qlite3_malloc]. 
2f840 20 5e 46 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a   ^Furthermore,.*
2f850 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  * the [temp_stor
2f860 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2f870 6d 61 5d 20 61 6c 77 61 79 73 20 61 73 73 75 6d  ma] always assum
2f880 65 73 20 74 68 61 74 20 61 6e 79 20 73 74 72 69  es that any stri
2f890 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68 69 73 20  ng.** that this 
2f8a0 76 61 72 69 61 62 6c 65 20 70 6f 69 6e 74 73 20  variable points 
2f8b0 74 6f 20 69 73 20 68 65 6c 64 20 69 6e 20 6d 65  to is held in me
2f8c0 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
2f8d0 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  om .** [sqlite3_
2f8e0 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20  malloc] and the 
2f8f0 70 72 61 67 6d 61 20 6d 61 79 20 61 74 74 65 6d  pragma may attem
2f900 70 74 20 74 6f 20 66 72 65 65 20 74 68 61 74 20  pt to free that 
2f910 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20  memory.** using 
2f920 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a  [sqlite3_free]..
2f930 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20 74 68 69  ** Hence, if thi
2f940 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 6f  s variable is mo
2f950 64 69 66 69 65 64 20 64 69 72 65 63 74 6c 79 2c  dified directly,
2f960 20 65 69 74 68 65 72 20 69 74 20 73 68 6f 75 6c   either it shoul
2f970 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c  d be.** made NUL
2f980 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20 70 6f 69  L or made to poi
2f990 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
2f9a0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
2f9b0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f  te3_malloc].** o
2f9c0 72 20 65 6c 73 65 20 74 68 65 20 75 73 65 20 6f  r else the use o
2f9d0 66 20 74 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72  f the [temp_stor
2f9e0 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67  e_directory prag
2f9f0 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65 20 61 76  ma] should be av
2fa00 6f 69 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  oided..*/.SQLITE
2fa10 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45  _API SQLITE_EXTE
2fa20 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  RN char *sqlite3
2fa30 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b  _temp_directory;
2fa40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fa50 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f 2d  : Test For Auto-
2fa60 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20 4b  Commit Mode.** K
2fa70 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63 6f  EYWORDS: {autoco
2fa80 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a  mmit mode}.**.**
2fa90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
2faa0 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20 69  t_autocommit() i
2fab0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2fac0 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a 20   non-zero or.** 
2fad0 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76 65  zero if the give
2fae0 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  n database conne
2faf0 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20 6e  ction is or is n
2fb00 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69 74  ot in autocommit
2fb10 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65 63   mode,.** respec
2fb20 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63 6f  tively.  ^Autoco
2fb30 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e 20  mmit mode is on 
2fb40 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 5e  by default..** ^
2fb50 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
2fb60 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 61  is disabled by a
2fb70 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d 65   [BEGIN] stateme
2fb80 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  nt..** ^Autocomm
2fb90 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65 6e  it mode is re-en
2fba0 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d 4d  abled by a [COMM
2fbb0 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43 4b  IT] or [ROLLBACK
2fbc0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72 74  ]..**.** If cert
2fbd0 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72 72  ain kinds of err
2fbe0 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20 73  ors occur on a s
2fbf0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
2fc00 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65 6e  a multi-statemen
2fc10 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e  t.** transaction
2fc20 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64 69   (errors includi
2fc30 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c 5d  ng [SQLITE_FULL]
2fc40 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  , [SQLITE_IOERR]
2fc50 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  ,.** [SQLITE_NOM
2fc60 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55 53  EM], [SQLITE_BUS
2fc70 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  Y], and [SQLITE_
2fc80 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65 6e  INTERRUPT]) then
2fc90 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63 74   the.** transact
2fca0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f 6c  ion might be rol
2fcb0 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
2fcc0 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e 6c  ically.  The onl
2fcd0 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e 64  y way to.** find
2fce0 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51 4c   out whether SQL
2fcf0 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
2fd00 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74 68  y rolled back th
2fd10 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61 66  e transaction af
2fd20 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20  ter.** an error 
2fd30 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20 66  is to use this f
2fd40 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49  unction..**.** I
2fd50 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  f another thread
2fd60 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75 74   changes the aut
2fd70 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20 6f  ocommit status o
2fd80 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
2fd90 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69  * connection whi
2fda0 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  le this routine 
2fdb0 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65 6e  is running, then
2fdc0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2fdd0 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
2fde0 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  d..*/.SQLITE_API
2fdf0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74   int sqlite3_get
2fe00 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69  _autocommit(sqli
2fe10 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
2fe20 50 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65  PI3REF: Find The
2fe30 20 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65   Database Handle
2fe40 20 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53   Of A Prepared S
2fe50 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e  tatement.**.** ^
2fe60 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68  The sqlite3_db_h
2fe70 61 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20  andle interface 
2fe80 72 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74  returns the [dat
2fe90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2fea0 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77  ] handle.** to w
2feb0 68 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64  hich a [prepared
2fec0 20 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f   statement] belo
2fed0 6e 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61  ngs.  ^The [data
2fee0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2fef0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2ff00 73 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c  sqlite3_db_handl
2ff10 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64  e is the same [d
2ff20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ff30 6f 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  on].** that was 
2ff40 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2ff50 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  nt.** to the [sq
2ff60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2ff70 28 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73  ()] call (or its
2ff80 20 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20   variants) that 
2ff90 77 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63  was used to.** c
2ffa0 72 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  reate the statem
2ffb0 65 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74  ent in the first
2ffc0 20 70 6c 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54   place..*/.SQLIT
2ffd0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73  E_API sqlite3 *s
2ffe0 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
2fff0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
30000 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30010 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
30020 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30030 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  nt.**.** ^This i
30040 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
30050 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
30060 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64  e next [prepared
30070 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65   statement] afte
30080 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63  r.** pStmt assoc
30090 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
300a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
300b0 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70  ion] pDb.  ^If p
300c0 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
300d0 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
300e0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
300f0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
30100 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
30110 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
30120 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
30130 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
30140 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72   pDb.  ^If no pr
30150 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30160 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68  .** satisfies th
30170 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20  e conditions of 
30180 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74  this routine, it
30190 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a   returns NULL..*
301a0 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61  *.** The [databa
301b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
301c0 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61  ointer D in a ca
301d0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
301e0 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29  3_next_stmt(D,S)
301f0 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20  ] must refer to 
30200 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
30210 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  .** connection a
30220 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  nd in particular
30230 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e   must not be a N
30240 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
30250 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
30260 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33  e3_stmt *sqlite3
30270 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74  _next_stmt(sqlit
30280 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33  e3 *pDb, sqlite3
30290 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
302a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
302b0 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62  Commit And Rollb
302c0 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  ack Notification
302d0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
302e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
302f0 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  mmit_hook() inte
30300 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
30310 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
30320 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
30330 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
30340 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
30350 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74  COMMIT | committ
30360 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ed]..** ^Any cal
30370 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
30380 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
30390 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
303a0 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
303b0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
303c0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
303d0 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65  rridden..** ^The
303e0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
303f0 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  k_hook() interfa
30400 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
30410 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
30420 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
30430 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
30440 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c  nsaction is [ROL
30450 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62  LBACK | rolled b
30460 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ack]..** ^Any ca
30470 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
30480 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
30490 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
304a0 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  k_hook().** for 
304b0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
304c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
304d0 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e  overridden..** ^
304e0 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
304f0 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
30500 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ugh to the callb
30510 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ack..** ^If the 
30520 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
30530 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
30540 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  on returns non-z
30550 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ero,.** then the
30560 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65   commit is conve
30570 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c  rted into a roll
30580 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  back..**.** ^The
30590 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
305a0 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20  hook(D,C,P) and 
305b0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
305c0 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e  _hook(D,C,P) fun
305d0 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e  ctions.** return
305e0 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20   the P argument 
305f0 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
30600 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61  s call of the sa
30610 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f  me function.** o
30620 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
30630 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30640 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a   D, or NULL for.
30650 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  ** the first cal
30660 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74  l for each funct
30670 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  ion on D..**.** 
30680 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70  The callback imp
30690 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
306a0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
306b0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
306c0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
306d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
306e0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61  t invoked the ca
306f0 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74  llback.  Any act
30700 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
30710 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
30720 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
30730 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
30740 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
30750 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
30760 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
30770 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
30780 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a  ered the commit.
30790 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68  ** or rollback h
307a0 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74  ook in the first
307b0 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20   place..** Note 
307c0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
307d0 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
307e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
307f0 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
30800 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
30810 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
30820 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
30830 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
30840 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
30850 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e  ^Registering a N
30860 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
30870 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
30880 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ck..**.** ^When 
30890 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  the commit hook 
308a0 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
308b0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
308c0 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f  he [COMMIT].** o
308d0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f  peration is allo
308e0 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  wed to continue 
308f0 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74  normally.  ^If t
30900 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a  he commit hook.*
30910 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  * returns non-ze
30920 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f  ro, then the [CO
30930 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74  MMIT] is convert
30940 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42  ed into a [ROLLB
30950 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ACK]..** ^The ro
30960 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69  llback hook is i
30970 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c  nvoked on a roll
30980 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74  back that result
30990 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a  s from a commit.
309a0 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e  ** hook returnin
309b0 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74  g non-zero, just
309c0 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20   as it would be 
309d0 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72  with any other r
309e0 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  ollback..**.** ^
309f0 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
30a00 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
30a10 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
30a20 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
30a30 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
30a40 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
30a50 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
30a60 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
30a70 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
30a80 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
30a90 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
30aa0 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
30ab0 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  ur..** ^The roll
30ac0 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
30ad0 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
30ae0 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30af0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
30b00 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  y rolled back be
30b10 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61  cause the databa
30b20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
30b30 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53   closed..**.** S
30b40 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
30b50 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
30b60 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
30b70 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
30b80 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  d *sqlite3_commi
30b90 74 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  t_hook(sqlite3*,
30ba0 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20   int(*)(void*), 
30bb0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
30bc0 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
30bd0 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73  _rollback_hook(s
30be0 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29  qlite3*, void(*)
30bf0 28 76 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29  (void *), void*)
30c00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
30c10 46 3a 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e  F: Data Change N
30c20 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c  otification Call
30c30 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
30c40 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f   sqlite3_update_
30c50 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65  hook() interface
30c60 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
30c70 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
30c80 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
30c90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30ca0 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20 74   identified by t
30cb0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
30cc0 74 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b  t.** to be invok
30cd0 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f  ed whenever a ro
30ce0 77 20 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e  w is updated, in
30cf0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
30d00 64 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  d..** ^Any callb
30d10 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
30d20 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68  vious call to th
30d30 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66  is function.** f
30d40 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  or the same data
30d50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
30d60 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a  is overridden..*
30d70 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
30d80 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70   argument is a p
30d90 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75  ointer to the fu
30da0 6e 63 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65  nction to invoke
30db0 20 77 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69   when a.** row i
30dc0 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72  s updated, inser
30dd0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a  ted or deleted..
30de0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
30df0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61  gument to the ca
30e00 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79  llback is a copy
30e10 20 6f 66 20 74 68 65 20 74 68 69 72 64 20 61 72   of the third ar
30e20 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c  gument.** to sql
30e30 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
30e40 28 29 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  ()..** ^The seco
30e50 6e 64 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75  nd callback argu
30e60 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b  ment is one of [
30e70 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20  SQLITE_INSERT], 
30e80 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c  [SQLITE_DELETE],
30e90 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55  .** or [SQLITE_U
30ea0 50 44 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e  PDATE], dependin
30eb0 67 20 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69  g on the operati
30ec0 6f 6e 20 74 68 61 74 20 63 61 75 73 65 64 20 74  on that caused t
30ed0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  he callback.** t
30ee0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  o be invoked..**
30ef0 20 5e 54 68 65 20 74 68 69 72 64 20 61 6e 64 20   ^The third and 
30f00 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73  fourth arguments
30f10 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
30f20 20 63 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72   contain pointer
30f30 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
30f40 62 61 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e  base and table n
30f50 61 6d 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ame containing t
30f60 68 65 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e  he affected row.
30f70 0a 2a 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63  .** ^The final c
30f80 61 6c 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65  allback paramete
30f90 72 20 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  r is the [rowid]
30fa0 20 6f 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20   of the row..** 
30fb0 5e 49 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20  ^In the case of 
30fc0 61 6e 20 75 70 64 61 74 65 2c 20 74 68 69 73 20  an update, this 
30fd0 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61  is the [rowid] a
30fe0 66 74 65 72 20 74 68 65 20 75 70 64 61 74 65 20  fter the update 
30ff0 74 61 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a  takes place..**.
31000 2a 2a 20 5e 28 54 68 65 20 75 70 64 61 74 65 20  ** ^(The update 
31010 68 6f 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f  hook is not invo
31020 6b 65 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61  ked when interna
31030 6c 20 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20  l system tables 
31040 61 72 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20  are.** modified 
31050 28 69 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73  (i.e. sqlite_mas
31060 74 65 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73  ter and sqlite_s
31070 65 71 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a  equence).)^.**.*
31080 2a 20 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e  * ^In the curren
31090 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  t implementation
310a0 2c 20 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f  , the update hoo
310b0 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f  k.** is not invo
310c0 6b 65 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61  ked when duplica
310d0 74 69 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65  tion rows are de
310e0 6c 65 74 65 64 20 62 65 63 61 75 73 65 20 6f 66  leted because of
310f0 20 61 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c   an.** [ON CONFL
31100 49 43 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43  ICT | ON CONFLIC
31110 54 20 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73  T REPLACE] claus
31120 65 2e 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20  e.  ^Nor is the 
31130 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
31140 6e 76 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73  nvoked when rows
31150 20 61 72 65 20 64 65 6c 65 74 65 64 20 75 73 69   are deleted usi
31160 6e 67 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65  ng the [truncate
31170 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a   optimization]..
31180 2a 2a 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e  ** The exception
31190 73 20 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69  s defined in thi
311a0 73 20 70 61 72 61 67 72 61 70 68 20 6d 69 67 68  s paragraph migh
311b0 74 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75  t change in a fu
311c0 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20  ture.** release 
311d0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
311e0 20 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b   The update hook
311f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
31200 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
31210 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
31220 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
31230 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31240 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
31250 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20  e update hook.  
31260 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
31270 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
31280 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
31290 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
312a0 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
312b0 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
312c0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
312d0 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
312e0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
312f0 75 70 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20  update hook..** 
31300 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
31310 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
31320 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
31330 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
31340 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
31350 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
31360 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
31370 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
31380 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
31390 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
313a0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c  3_update_hook(D,
313b0 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  C,P) function.**
313c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 50 20 61   returns the P a
313d0 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
313e0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a   previous call.*
313f0 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64  * on the same [d
31400 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
31410 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66  on] D, or NULL f
31420 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  or.** the first 
31430 63 61 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  call on D..**.**
31440 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
31450 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
31460 6f 6b 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ok()] and [sqlit
31470 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
31480 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
31490 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
314a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75   void *sqlite3_u
314b0 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
314c0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
314d0 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
314e0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
314f0 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
31500 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
31510 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
31520 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
31530 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
31540 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59  ger Cache.** KEY
31550 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63  WORDS: {shared c
31560 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ache}.**.** ^(Th
31570 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  is routine enabl
31580 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
31590 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68  he sharing of th
315a0 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65  e database cache
315b0 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64  .** and schema d
315c0 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62  ata structures b
315d0 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65  etween [database
315e0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f   connection | co
315f0 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f  nnections].** to
31600 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
31610 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65  se. Sharing is e
31620 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
31630 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a  gument is true.*
31640 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69  * and disabled i
31650 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
31660 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a  s false.)^.**.**
31670 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67 20   ^Cache sharing 
31680 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
31690 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
316a0 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a  ntire process..*
316b0 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e  * This is a chan
316c0 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20  ge as of SQLite 
316d0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49  version 3.5.0. I
316e0 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
316f0 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73   of SQLite,.** s
31700 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c  haring was enabl
31710 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
31720 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
31730 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
31740 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68 61   ^(The cache sha
31750 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79  ring mode set by
31760 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
31770 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73  effects all subs
31780 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
31790 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
317a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
317b0 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73  en_v2()], and [s
317c0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
317d0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61  ..** Existing da
317e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
317f0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20  ns continue use 
31800 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  the sharing mode
31810 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20  .** that was in 
31820 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69  effect at the ti
31830 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65  me they were ope
31840 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ned.)^.**.** ^(T
31850 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
31860 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
31870 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
31880 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
31890 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65  isabled.** succe
318a0 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72  ssfully.  An [er
318b0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
318c0 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e  urned otherwise.
318d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64  )^.**.** ^Shared
318e0 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
318f0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42  ed by default. B
31900 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68  ut this might ch
31910 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72  ange in.** futur
31920 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
31930 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69  Lite.  Applicati
31940 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62  ons that care ab
31950 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  out shared.** ca
31960 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75  che setting shou
31970 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63  ld set it explic
31980 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  itly..**.** See 
31990 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53  Also:  [SQLite S
319a0 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65  hared-Cache Mode
319b0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
319c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
319d0 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28  le_shared_cache(
319e0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
319f0 49 33 52 45 46 3a 20 41 74 74 65 6d 70 74 20 54  I3REF: Attempt T
31a00 6f 20 46 72 65 65 20 48 65 61 70 20 4d 65 6d 6f  o Free Heap Memo
31a10 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ry.**.** ^The sq
31a20 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
31a30 6d 6f 72 79 28 29 20 69 6e 74 65 72 66 61 63 65  mory() interface
31a40 20 61 74 74 65 6d 70 74 73 20 74 6f 20 66 72 65   attempts to fre
31a50 65 20 4e 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  e N bytes.** of 
31a60 68 65 61 70 20 6d 65 6d 6f 72 79 20 62 79 20 64  heap memory by d
31a70 65 61 6c 6c 6f 63 61 74 69 6e 67 20 6e 6f 6e 2d  eallocating non-
31a80 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d 6f 72 79  essential memory
31a90 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 0a 2a 2a 20   allocations.** 
31aa0 68 65 6c 64 20 62 79 20 74 68 65 20 64 61 74 61  held by the data
31ab0 62 61 73 65 20 6c 69 62 72 61 72 79 2e 20 20 20  base library.   
31ac0 4d 65 6d 6f 72 79 20 75 73 65 64 20 74 6f 20 63  Memory used to c
31ad0 61 63 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a  ache database.**
31ae0 20 70 61 67 65 73 20 74 6f 20 69 6d 70 72 6f 76   pages to improv
31af0 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 73  e performance is
31b00 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 6e   an example of n
31b10 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65 6d  on-essential mem
31b20 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  ory..** ^sqlite3
31b30 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28  _release_memory(
31b40 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  ) returns the nu
31b50 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 61 63  mber of bytes ac
31b60 74 75 61 6c 6c 79 20 66 72 65 65 64 2c 0a 2a 2a  tually freed,.**
31b70 20 77 68 69 63 68 20 6d 69 67 68 74 20 62 65 20   which might be 
31b80 6d 6f 72 65 20 6f 72 20 6c 65 73 73 20 74 68 61  more or less tha
31b90 6e 20 74 68 65 20 61 6d 6f 75 6e 74 20 72 65 71  n the amount req
31ba0 75 65 73 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  uested..** ^The 
31bb0 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f  sqlite3_release_
31bc0 6d 65 6d 6f 72 79 28 29 20 72 6f 75 74 69 6e 65  memory() routine
31bd0 20 69 73 20 61 20 6e 6f 2d 6f 70 20 72 65 74 75   is a no-op retu
31be0 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a 2a 20 69 66  rning zero.** if
31bf0 20 53 51 4c 69 74 65 20 69 73 20 6e 6f 74 20 63   SQLite is not c
31c00 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
31c10 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f  LITE_ENABLE_MEMO
31c20 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a  RY_MANAGEMENT]..
31c30 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
31c40 74 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  t sqlite3_releas
31c50 65 5f 6d 65 6d 6f 72 79 28 69 6e 74 29 3b 0a 0a  e_memory(int);..
31c60 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31c70 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69 74 20 4f  Impose A Limit O
31c80 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a 2a 0a 2a  n Heap Size.**.*
31c90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73  * ^The sqlite3_s
31ca0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
31cb0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
31cc0 73 20 61 6e 64 2f 6f 72 20 71 75 65 72 69 65 73  s and/or queries
31cd0 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20 6c 69 6d   the.** soft lim
31ce0 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f 75 6e 74  it on the amount
31cf0 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
31d00 74 68 61 74 20 6d 61 79 20 62 65 20 61 6c 6c 6f  that may be allo
31d10 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e  cated by SQLite.
31d20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73 74 72 69  .** ^SQLite stri
31d30 76 65 73 20 74 6f 20 6b 65 65 70 20 68 65 61 70  ves to keep heap
31d40 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69 7a 61 74   memory utilizat
31d50 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65 20 73 6f  ion below the so
31d60 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69 6d 69 74  ft heap.** limit
31d70 20 62 79 20 72 65 64 75 63 69 6e 67 20 74 68 65   by reducing the
31d80 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73   number of pages
31d90 20 68 65 6c 64 20 69 6e 20 74 68 65 20 70 61 67   held in the pag
31da0 65 20 63 61 63 68 65 0a 2a 2a 20 61 73 20 68 65  e cache.** as he
31db0 61 70 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 73  ap memory usages
31dc0 20 61 70 70 72 6f 61 63 68 65 73 20 74 68 65 20   approaches the 
31dd0 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  limit..** ^The s
31de0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
31df0 73 20 22 73 6f 66 74 22 20 62 65 63 61 75 73 65  s "soft" because
31e00 20 65 76 65 6e 20 74 68 6f 75 67 68 20 53 51 4c   even though SQL
31e10 69 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 73  ite strives to s
31e20 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20 74 68 65  tay.** below the
31e30 20 6c 69 6d 69 74 2c 20 69 74 20 77 69 6c 6c 20   limit, it will 
31e40 65 78 63 65 65 64 20 74 68 65 20 6c 69 6d 69 74  exceed the limit
31e50 20 72 61 74 68 65 72 20 74 68 61 6e 20 67 65 6e   rather than gen
31e60 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b 53 51 4c  erate.** an [SQL
31e70 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72 72 6f 72  ITE_NOMEM] error
31e80 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
31e90 73 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  s, the soft heap
31ea0 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73 20 61 64   limit .** is ad
31eb0 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  visory only..**.
31ec0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 20 76  ** ^The return v
31ed0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
31ee0 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
31ef0 74 36 34 28 29 20 69 73 20 74 68 65 20 73 69 7a  t64() is the siz
31f00 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73 6f 66 74  e of.** the soft
31f10 20 68 65 61 70 20 6c 69 6d 69 74 20 70 72 69 6f   heap limit prio
31f20 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 2e 20 20  r to the call.  
31f30 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74  ^If the argument
31f40 20 4e 20 69 73 20 6e 65 67 61 74 69 76 65 0a 2a   N is negative.*
31f50 2a 20 74 68 65 6e 20 6e 6f 20 63 68 61 6e 67 65  * then no change
31f60 20 69 73 20 6d 61 64 65 20 74 6f 20 74 68 65 20   is made to the 
31f70 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 2e  soft heap limit.
31f80 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 75 72    Hence, the cur
31f90 72 65 6e 74 0a 2a 2a 20 73 69 7a 65 20 6f 66 20  rent.** size of 
31fa0 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
31fb0 6d 69 74 20 63 61 6e 20 62 65 20 64 65 74 65 72  mit can be deter
31fc0 6d 69 6e 65 64 20 62 79 20 69 6e 76 6f 6b 69 6e  mined by invokin
31fd0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 6f 66  g.** sqlite3_sof
31fe0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
31ff0 20 77 69 74 68 20 61 20 6e 65 67 61 74 69 76 65   with a negative
32000 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
32010 20 5e 49 66 20 74 68 65 20 61 72 67 75 6d 65 6e   ^If the argumen
32020 74 20 4e 20 69 73 20 7a 65 72 6f 20 74 68 65 6e  t N is zero then
32030 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
32040 69 6d 69 74 20 69 73 20 64 69 73 61 62 6c 65 64  imit is disabled
32050 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 6f  ..**.** ^(The so
32060 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
32070 20 6e 6f 74 20 65 6e 66 6f 72 63 65 64 20 69 6e   not enforced in
32080 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
32090 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69  lementation.** i
320a0 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66  f one or more of
320b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 6f 6e 64 69   following condi
320c0 74 69 6f 6e 73 20 61 72 65 20 74 72 75 65 3a 0a  tions are true:.
320d0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
320e0 69 3e 20 54 68 65 20 73 6f 66 74 20 68 65 61 70  i> The soft heap
320f0 20 6c 69 6d 69 74 20 69 73 20 73 65 74 20 74 6f   limit is set to
32100 20 7a 65 72 6f 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d   zero..** <li> M
32110 65 6d 6f 72 79 20 61 63 63 6f 75 6e 74 69 6e 67  emory accounting
32120 20 69 73 20 64 69 73 61 62 6c 65 64 20 75 73 69   is disabled usi
32130 6e 67 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  ng a combination
32140 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20 20 20 20   of the.**      
32150 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d  [sqlite3_config]
32160 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  ([SQLITE_CONFIG_
32170 4d 45 4d 53 54 41 54 55 53 5d 2c 2e 2e 2e 29 20  MEMSTATUS],...) 
32180 73 74 61 72 74 2d 74 69 6d 65 20 6f 70 74 69 6f  start-time optio
32190 6e 20 61 6e 64 0a 2a 2a 20 20 20 20 20 20 74 68  n and.**      th
321a0 65 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c  e [SQLITE_DEFAUL
321b0 54 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6d  T_MEMSTATUS] com
321c0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
321d0 2e 0a 2a 2a 20 3c 6c 69 3e 20 41 6e 20 61 6c 74  ..** <li> An alt
321e0 65 72 6e 61 74 69 76 65 20 70 61 67 65 20 63 61  ernative page ca
321f0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
32200 6f 6e 20 69 73 20 73 70 65 63 69 66 65 64 20 75  on is specifed u
32210 73 69 6e 67 0a 2a 2a 20 20 20 20 20 20 5b 73 71  sing.**      [sq
32220 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
32230 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
32240 43 48 45 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c  CHE],...)..** <l
32250 69 3e 20 54 68 65 20 70 61 67 65 20 63 61 63 68  i> The page cach
32260 65 20 61 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d  e allocates from
32270 20 69 74 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20   its own memory 
32280 70 6f 6f 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a  pool supplied.**
32290 20 20 20 20 20 20 62 79 20 5b 73 71 6c 69 74 65        by [sqlite
322a0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
322b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
322c0 48 45 5d 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20  HE],...) rather 
322d0 74 68 61 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f  than.**      fro
322e0 6d 20 74 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c  m the heap..** <
322f0 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67  /ul>)^.**.** Beg
32300 69 6e 6e 69 6e 67 20 77 69 74 68 20 53 51 4c 69  inning with SQLi
32310 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33  te version 3.7.3
32320 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
32330 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65  limit is enforce
32340 64 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  d.** regardless 
32350 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
32360 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  t the [SQLITE_EN
32370 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
32380 47 45 4d 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69  GEMENT].** compi
32390 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
323a0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68  s invoked.  With
323b0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
323c0 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
323d0 54 5d 2c 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20  T],.** the soft 
323e0 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20 65 6e  heap limit is en
323f0 66 6f 72 63 65 64 20 6f 6e 20 65 76 65 72 79 20  forced on every 
32400 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
32410 6e 2e 20 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b  n.  Without.** [
32420 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
32430 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
32440 2c 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  , the soft heap 
32450 6c 69 6d 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e  limit is only en
32460 66 6f 72 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d  forced.** when m
32470 65 6d 6f 72 79 20 69 73 20 61 6c 6c 6f 63 61 74  emory is allocat
32480 65 64 20 62 79 20 74 68 65 20 70 61 67 65 20 63  ed by the page c
32490 61 63 68 65 2e 20 20 54 65 73 74 69 6e 67 20 73  ache.  Testing s
324a0 75 67 67 65 73 74 73 20 74 68 61 74 20 62 65 63  uggests that bec
324b0 61 75 73 65 0a 2a 2a 20 74 68 65 20 70 61 67 65  ause.** the page
324c0 20 63 61 63 68 65 20 69 73 20 74 68 65 20 70 72   cache is the pr
324d0 65 64 6f 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79  edominate memory
324e0 20 75 73 65 72 20 69 6e 20 53 51 4c 69 74 65 2c   user in SQLite,
324f0 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61   most.** applica
32500 74 69 6f 6e 73 20 77 69 6c 6c 20 61 63 68 69 65  tions will achie
32510 76 65 20 61 64 65 71 75 61 74 65 20 73 6f 66 74  ve adequate soft
32520 20 68 65 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f   heap limit enfo
32530 72 63 65 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a  rcement without.
32540 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 5b 53  ** the use of [S
32550 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
32560 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e  ORY_MANAGEMENT].
32570 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 69 72 63 75  .**.** The circu
32580 6d 73 74 61 6e 63 65 73 20 75 6e 64 65 72 20 77  mstances under w
32590 68 69 63 68 20 53 51 4c 69 74 65 20 77 69 6c 6c  hich SQLite will
325a0 20 65 6e 66 6f 72 63 65 20 74 68 65 20 73 6f 66   enforce the sof
325b0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 6d 61 79  t heap limit may
325c0 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 66  .** changes in f
325d0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
325e0 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
325f0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
32600 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 73 6f  int64 sqlite3_so
32610 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
32620 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e 29  sqlite3_int64 N)
32630 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32640 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 53 6f  F: Deprecated So
32650 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20 49 6e  ft Heap Limit In
32660 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50 52 45  terface.** DEPRE
32670 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73  CATED.**.** This
32680 20 69 73 20 61 20 64 65 70 72 65 63 61 74 65 64   is a deprecated
32690 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
326a0 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
326b0 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
326c0 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 69   interface.  Thi
326d0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72 6f  s routine is pro
326e0 76 69 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  vided for histor
326f0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
32700 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c  ty.** only.  All
32710 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
32720 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  s should use the
32730 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  .** [sqlite3_sof
32740 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
32750 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61 74 68  ] interface rath
32760 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e 65  er than this one
32770 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
32780 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
32790 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  D void sqlite3_s
327a0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 28 69  oft_heap_limit(i
327b0 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt N);.../*.** C
327c0 41 50 49 33 52 45 46 3a 20 45 78 74 72 61 63 74  API3REF: Extract
327d0 20 4d 65 74 61 64 61 74 61 20 41 62 6f 75 74 20   Metadata About 
327e0 41 20 43 6f 6c 75 6d 6e 20 4f 66 20 41 20 54 61  A Column Of A Ta
327f0 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ble.**.** ^This 
32800 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
32810 6d 65 74 61 64 61 74 61 20 61 62 6f 75 74 20 61  metadata about a
32820 20 73 70 65 63 69 66 69 63 20 63 6f 6c 75 6d 6e   specific column
32830 20 6f 66 20 61 20 73 70 65 63 69 66 69 63 0a 2a   of a specific.*
32840 2a 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  * database table
32850 20 61 63 63 65 73 73 69 62 6c 65 20 75 73 69 6e   accessible usin
32860 67 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  g the [database 
32870 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
32880 6c 65 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20  le.** passed as 
32890 74 68 65 20 66 69 72 73 74 20 66 75 6e 63 74 69  the first functi
328a0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  on argument..**.
328b0 2a 2a 20 5e 54 68 65 20 63 6f 6c 75 6d 6e 20 69  ** ^The column i
328c0 73 20 69 64 65 6e 74 69 66 69 65 64 20 62 79 20  s identified by 
328d0 74 68 65 20 73 65 63 6f 6e 64 2c 20 74 68 69 72  the second, thir
328e0 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61 72  d and fourth par
328f0 61 6d 65 74 65 72 73 20 74 6f 0a 2a 2a 20 74 68  ameters to.** th
32900 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 54 68  is function. ^Th
32910 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
32920 65 72 20 69 73 20 65 69 74 68 65 72 20 74 68 65  er is either the
32930 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
32940 61 62 61 73 65 0a 2a 2a 20 28 69 2e 65 2e 20 22  abase.** (i.e. "
32950 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 20 6f  main", "temp", o
32960 72 20 61 6e 20 61 74 74 61 63 68 65 64 20 64 61  r an attached da
32970 74 61 62 61 73 65 29 20 63 6f 6e 74 61 69 6e 69  tabase) containi
32980 6e 67 20 74 68 65 20 73 70 65 63 69 66 69 65 64  ng the specified
32990 0a 2a 2a 20 74 61 62 6c 65 20 6f 72 20 4e 55 4c  .** table or NUL
329a0 4c 2e 20 5e 49 66 20 69 74 20 69 73 20 4e 55 4c  L. ^If it is NUL
329b0 4c 2c 20 74 68 65 6e 20 61 6c 6c 20 61 74 74 61  L, then all atta
329c0 63 68 65 64 20 64 61 74 61 62 61 73 65 73 20 61  ched databases a
329d0 72 65 20 73 65 61 72 63 68 65 64 0a 2a 2a 20 66  re searched.** f
329e0 6f 72 20 74 68 65 20 74 61 62 6c 65 20 75 73 69  or the table usi
329f0 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
32a00 72 69 74 68 6d 20 75 73 65 64 20 62 79 20 74 68  rithm used by th
32a10 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
32a20 65 20 74 6f 0a 2a 2a 20 72 65 73 6f 6c 76 65 20  e to.** resolve 
32a30 75 6e 71 75 61 6c 69 66 69 65 64 20 74 61 62 6c  unqualified tabl
32a40 65 20 72 65 66 65 72 65 6e 63 65 73 2e 0a 2a 2a  e references..**
32a50 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
32a60 6e 64 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  nd fourth parame
32a70 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75 6e  ters to this fun
32a80 63 74 69 6f 6e 20 61 72 65 20 74 68 65 20 74 61  ction are the ta
32a90 62 6c 65 20 61 6e 64 20 63 6f 6c 75 6d 6e 0a 2a  ble and column.*
32aa0 2a 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 65  * name of the de
32ab0 73 69 72 65 64 20 63 6f 6c 75 6d 6e 2c 20 72 65  sired column, re
32ac0 73 70 65 63 74 69 76 65 6c 79 2e 20 4e 65 69 74  spectively. Neit
32ad0 68 65 72 20 6f 66 20 74 68 65 73 65 20 70 61 72  her of these par
32ae0 61 6d 65 74 65 72 73 0a 2a 2a 20 6d 61 79 20 62  ameters.** may b
32af0 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4d  e NULL..**.** ^M
32b00 65 74 61 64 61 74 61 20 69 73 20 72 65 74 75 72  etadata is retur
32b10 6e 65 64 20 62 79 20 77 72 69 74 69 6e 67 20 74  ned by writing t
32b20 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 6c 6f 63  o the memory loc
32b30 61 74 69 6f 6e 73 20 70 61 73 73 65 64 20 61 73  ations passed as
32b40 20 74 68 65 20 35 74 68 0a 2a 2a 20 61 6e 64 20   the 5th.** and 
32b50 73 75 62 73 65 71 75 65 6e 74 20 70 61 72 61 6d  subsequent param
32b60 65 74 65 72 73 20 74 6f 20 74 68 69 73 20 66 75  eters to this fu
32b70 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79 20 6f 66 20  nction. ^Any of 
32b80 74 68 65 73 65 20 61 72 67 75 6d 65 6e 74 73 20  these arguments 
32b90 6d 61 79 20 62 65 0a 2a 2a 20 4e 55 4c 4c 2c 20  may be.** NULL, 
32ba0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 74 68  in which case th
32bb0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
32bc0 65 6c 65 6d 65 6e 74 20 6f 66 20 6d 65 74 61 64  element of metad
32bd0 61 74 61 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ata is omitted..
32be0 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f 63 6b 71 75  **.** ^(<blockqu
32bf0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
32c00 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
32c10 72 3e 3c 74 68 3e 20 50 61 72 61 6d 65 74 65 72  r><th> Parameter
32c20 20 3c 74 68 3e 20 4f 75 74 70 75 74 3c 62 72 3e   <th> Output<br>
32c30 54 79 70 65 20 3c 74 68 3e 20 20 44 65 73 63 72  Type <th>  Descr
32c40 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  iption.**.** <tr
32c50 3e 3c 74 64 3e 20 35 74 68 20 3c 74 64 3e 20 63  ><td> 5th <td> c
32c60 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
32c70 44 61 74 61 20 74 79 70 65 0a 2a 2a 20 3c 74 72  Data type.** <tr
32c80 3e 3c 74 64 3e 20 36 74 68 20 3c 74 64 3e 20 63  ><td> 6th <td> c
32c90 6f 6e 73 74 20 63 68 61 72 2a 20 3c 74 64 3e 20  onst char* <td> 
32ca0 4e 61 6d 65 20 6f 66 20 64 65 66 61 75 6c 74 20  Name of default 
32cb0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
32cc0 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 37  ce.** <tr><td> 7
32cd0 74 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20  th <td> int     
32ce0 20 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66      <td> True if
32cf0 20 63 6f 6c 75 6d 6e 20 68 61 73 20 61 20 4e 4f   column has a NO
32d00 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
32d10 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 38 74  t.** <tr><td> 8t
32d20 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
32d30 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
32d40 63 6f 6c 75 6d 6e 20 69 73 20 70 61 72 74 20 6f  column is part o
32d50 66 20 74 68 65 20 50 52 49 4d 41 52 59 20 4b 45  f the PRIMARY KE
32d60 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 39 74  Y.** <tr><td> 9t
32d70 68 20 3c 74 64 3e 20 69 6e 74 20 20 20 20 20 20  h <td> int      
32d80 20 20 20 3c 74 64 3e 20 54 72 75 65 20 69 66 20     <td> True if 
32d90 63 6f 6c 75 6d 6e 20 69 73 20 5b 41 55 54 4f 49  column is [AUTOI
32da0 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a 20 3c 2f 74  NCREMENT].** </t
32db0 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
32dc0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
32dd0 54 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  The memory point
32de0 65 64 20 74 6f 20 62 79 20 74 68 65 20 63 68 61  ed to by the cha
32df0 72 61 63 74 65 72 20 70 6f 69 6e 74 65 72 73 20  racter pointers 
32e00 72 65 74 75 72 6e 65 64 20 66 6f 72 20 74 68 65  returned for the
32e10 0a 2a 2a 20 64 65 63 6c 61 72 61 74 69 6f 6e 20  .** declaration 
32e20 74 79 70 65 20 61 6e 64 20 63 6f 6c 6c 61 74 69  type and collati
32e30 6f 6e 20 73 65 71 75 65 6e 63 65 20 69 73 20 76  on sequence is v
32e40 61 6c 69 64 20 6f 6e 6c 79 20 75 6e 74 69 6c 20  alid only until 
32e50 74 68 65 20 6e 65 78 74 0a 2a 2a 20 63 61 6c 6c  the next.** call
32e60 20 74 6f 20 61 6e 79 20 53 51 4c 69 74 65 20 41   to any SQLite A
32e70 50 49 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  PI function..**.
32e80 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
32e90 66 69 65 64 20 74 61 62 6c 65 20 69 73 20 61 63  fied table is ac
32ea0 74 75 61 6c 6c 79 20 61 20 76 69 65 77 2c 20 61  tually a view, a
32eb0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
32ec0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
32ed0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
32ee0 69 65 64 20 63 6f 6c 75 6d 6e 20 69 73 20 22 72  ied column is "r
32ef0 6f 77 69 64 22 2c 20 22 6f 69 64 22 20 6f 72 20  owid", "oid" or 
32f00 22 5f 72 6f 77 69 64 5f 22 20 61 6e 64 20 61 6e  "_rowid_" and an
32f10 0a 2a 2a 20 5b 49 4e 54 45 47 45 52 20 50 52 49  .** [INTEGER PRI
32f20 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e  MARY KEY] column
32f30 20 68 61 73 20 62 65 65 6e 20 65 78 70 6c 69 63   has been explic
32f40 69 74 6c 79 20 64 65 63 6c 61 72 65 64 2c 20 74  itly declared, t
32f50 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
32f60 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
32f70 20 73 65 74 20 66 6f 72 20 74 68 65 20 65 78 70   set for the exp
32f80 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
32f90 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49 66 20 74 68   column. ^(If th
32fa0 65 72 65 20 69 73 20 6e 6f 0a 2a 2a 20 65 78 70  ere is no.** exp
32fb0 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64  licitly declared
32fc0 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
32fd0 59 20 4b 45 59 5d 20 63 6f 6c 75 6d 6e 2c 20 74  Y KEY] column, t
32fe0 68 65 6e 20 74 68 65 20 6f 75 74 70 75 74 0a 2a  hen the output.*
32ff0 2a 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  * parameters are
33000 20 73 65 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a   set as follows:
33010 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
33020 20 20 20 20 64 61 74 61 20 74 79 70 65 3a 20 22      data type: "
33030 49 4e 54 45 47 45 52 22 0a 2a 2a 20 20 20 20 20  INTEGER".**     
33040 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
33050 63 65 3a 20 22 42 49 4e 41 52 59 22 0a 2a 2a 20  ce: "BINARY".** 
33060 20 20 20 20 6e 6f 74 20 6e 75 6c 6c 3a 20 30 0a      not null: 0.
33070 2a 2a 20 20 20 20 20 70 72 69 6d 61 72 79 20 6b  **     primary k
33080 65 79 3a 20 31 0a 2a 2a 20 20 20 20 20 61 75 74  ey: 1.**     aut
33090 6f 20 69 6e 63 72 65 6d 65 6e 74 3a 20 30 0a 2a  o increment: 0.*
330a0 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a 2a  * </pre>)^.**.**
330b0 20 5e 28 54 68 69 73 20 66 75 6e 63 74 69 6f 6e   ^(This function
330c0 20 6d 61 79 20 6c 6f 61 64 20 6f 6e 65 20 6f 72   may load one or
330d0 20 6d 6f 72 65 20 73 63 68 65 6d 61 73 20 66 72   more schemas fr
330e0 6f 6d 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  om database file
330f0 73 2e 20 49 66 20 61 6e 0a 2a 2a 20 65 72 72 6f  s. If an.** erro
33100 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
33110 74 68 69 73 20 70 72 6f 63 65 73 73 2c 20 6f 72  this process, or
33120 20 69 66 20 74 68 65 20 72 65 71 75 65 73 74 65   if the requeste
33130 64 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  d table or colum
33140 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 66  n.** cannot be f
33150 6f 75 6e 64 2c 20 61 6e 20 5b 65 72 72 6f 72 20  ound, an [error 
33160 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65  code] is returne
33170 64 20 61 6e 64 20 61 6e 20 65 72 72 6f 72 20 6d  d and an error m
33180 65 73 73 61 67 65 20 6c 65 66 74 0a 2a 2a 20 69  essage left.** i
33190 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
331a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 6f 20  connection] (to 
331b0 62 65 20 72 65 74 72 69 65 76 65 64 20 75 73 69  be retrieved usi
331c0 6e 67 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  ng sqlite3_errms
331d0 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  g()).)^.**.** ^T
331e0 68 69 73 20 41 50 49 20 69 73 20 6f 6e 6c 79 20  his API is only 
331f0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
33200 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
33210 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
33220 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
33230 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
33240 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
33250 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
33260 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
33270 6e 74 20 73 71 6c 69 74 65 33 5f 74 61 62 6c 65  nt sqlite3_table
33280 5f 63 6f 6c 75 6d 6e 5f 6d 65 74 61 64 61 74 61  _column_metadata
33290 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
332a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
332b0 2f 2a 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 68 61  /* Connection ha
332c0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
332d0 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20  char *zDbName,  
332e0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
332f0 65 20 6e 61 6d 65 20 6f 72 20 4e 55 4c 4c 20 2a  e name or NULL *
33300 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
33310 7a 54 61 62 6c 65 4e 61 6d 65 2c 20 20 20 20 20  zTableName,     
33320 2f 2a 20 54 61 62 6c 65 20 6e 61 6d 65 20 2a 2f  /* Table name */
33330 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33340 43 6f 6c 75 6d 6e 4e 61 6d 65 2c 20 20 20 20 2f  ColumnName,    /
33350 2a 20 43 6f 6c 75 6d 6e 20 6e 61 6d 65 20 2a 2f  * Column name */
33360 0a 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a  .  char const **
33370 70 7a 44 61 74 61 54 79 70 65 2c 20 20 20 20 2f  pzDataType,    /
33380 2a 20 4f 55 54 50 55 54 3a 20 44 65 63 6c 61 72  * OUTPUT: Declar
33390 65 64 20 64 61 74 61 20 74 79 70 65 20 2a 2f 0a  ed data type */.
333a0 20 20 63 68 61 72 20 63 6f 6e 73 74 20 2a 2a 70    char const **p
333b0 7a 43 6f 6c 6c 53 65 71 2c 20 20 20 20 20 2f 2a  zCollSeq,     /*
333c0 20 4f 55 54 50 55 54 3a 20 43 6f 6c 6c 61 74 69   OUTPUT: Collati
333d0 6f 6e 20 73 65 71 75 65 6e 63 65 20 6e 61 6d 65  on sequence name
333e0 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 4e 6f 74 4e   */.  int *pNotN
333f0 75 6c 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20  ull,            
33400 20 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75    /* OUTPUT: Tru
33410 65 20 69 66 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f  e if NOT NULL co
33420 6e 73 74 72 61 69 6e 74 20 65 78 69 73 74 73 20  nstraint exists 
33430 2a 2f 0a 20 20 69 6e 74 20 2a 70 50 72 69 6d 61  */.  int *pPrima
33440 72 79 4b 65 79 2c 20 20 20 20 20 20 20 20 20 20  ryKey,          
33450 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
33460 20 69 66 20 63 6f 6c 75 6d 6e 20 70 61 72 74 20   if column part 
33470 6f 66 20 50 4b 20 2a 2f 0a 20 20 69 6e 74 20 2a  of PK */.  int *
33480 70 41 75 74 6f 69 6e 63 20 20 20 20 20 20 20 20  pAutoinc        
33490 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54         /* OUTPUT
334a0 3a 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  : True if column
334b0 20 69 73 20 61 75 74 6f 2d 69 6e 63 72 65 6d 65   is auto-increme
334c0 6e 74 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nt */.);../*.** 
334d0 43 41 50 49 33 52 45 46 3a 20 4c 6f 61 64 20 41  CAPI3REF: Load A
334e0 6e 20 45 78 74 65 6e 73 69 6f 6e 0a 2a 2a 0a 2a  n Extension.**.*
334f0 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
33500 65 20 6c 6f 61 64 73 20 61 6e 20 53 51 4c 69 74  e loads an SQLit
33510 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72  e extension libr
33520 61 72 79 20 66 72 6f 6d 20 74 68 65 20 6e 61 6d  ary from the nam
33530 65 64 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed file..**.** ^
33540 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
33550 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
33560 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
33570 74 6f 20 6c 6f 61 64 20 61 6e 0a 2a 2a 20 53 51  to load an.** SQ
33580 4c 69 74 65 20 65 78 74 65 6e 73 69 6f 6e 20 6c  Lite extension l
33590 69 62 72 61 72 79 20 63 6f 6e 74 61 69 6e 65 64  ibrary contained
335a0 20 69 6e 20 74 68 65 20 66 69 6c 65 20 7a 46 69   in the file zFi
335b0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65  le..**.** ^The e
335c0 6e 74 72 79 20 70 6f 69 6e 74 20 69 73 20 7a 50  ntry point is zP
335d0 72 6f 63 2e 0a 2a 2a 20 5e 7a 50 72 6f 63 20 6d  roc..** ^zProc m
335e0 61 79 20 62 65 20 30 2c 20 69 6e 20 77 68 69 63  ay be 0, in whic
335f0 68 20 63 61 73 65 20 74 68 65 20 6e 61 6d 65 20  h case the name 
33600 6f 66 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  of the entry poi
33610 6e 74 0a 2a 2a 20 64 65 66 61 75 6c 74 73 20 74  nt.** defaults t
33620 6f 20 22 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  o "sqlite3_exten
33630 73 69 6f 6e 5f 69 6e 69 74 22 2e 0a 2a 2a 20 5e  sion_init"..** ^
33640 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 6f 61 64  The sqlite3_load
33650 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 69 6e 74  _extension() int
33660 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
33670 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  * [SQLITE_OK] on
33680 20 73 75 63 63 65 73 73 20 61 6e 64 20 5b 53 51   success and [SQ
33690 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 73  LITE_ERROR] if s
336a0 6f 6d 65 74 68 69 6e 67 20 67 6f 65 73 20 77 72  omething goes wr
336b0 6f 6e 67 2e 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ong..** ^If an e
336c0 72 72 6f 72 20 6f 63 63 75 72 73 20 61 6e 64 20  rror occurs and 
336d0 70 7a 45 72 72 4d 73 67 20 69 73 20 6e 6f 74 20  pzErrMsg is not 
336e0 30 2c 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  0, then the.** [
336f0 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74  sqlite3_load_ext
33700 65 6e 73 69 6f 6e 28 29 5d 20 69 6e 74 65 72 66  ension()] interf
33710 61 63 65 20 73 68 61 6c 6c 20 61 74 74 65 6d 70  ace shall attemp
33720 74 20 74 6f 0a 2a 2a 20 66 69 6c 6c 20 2a 70 7a  t to.** fill *pz
33730 45 72 72 4d 73 67 20 77 69 74 68 20 65 72 72 6f  ErrMsg with erro
33740 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 73  r message text s
33750 74 6f 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 0a  tored in memory.
33760 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ** obtained from
33770 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
33780 28 29 5d 2e 20 54 68 65 20 63 61 6c 6c 69 6e 67  ()]. The calling
33790 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 68 6f   function.** sho
337a0 75 6c 64 20 66 72 65 65 20 74 68 69 73 20 6d 65  uld free this me
337b0 6d 6f 72 79 20 62 79 20 63 61 6c 6c 69 6e 67 20  mory by calling 
337c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
337d0 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73 69  ..**.** ^Extensi
337e0 6f 6e 20 6c 6f 61 64 69 6e 67 20 6d 75 73 74 20  on loading must 
337f0 62 65 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  be enabled using
33800 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61  .** [sqlite3_ena
33810 62 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69  ble_load_extensi
33820 6f 6e 28 29 5d 20 70 72 69 6f 72 20 74 6f 20 63  on()] prior to c
33830 61 6c 6c 69 6e 67 20 74 68 69 73 20 41 50 49 2c  alling this API,
33840 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e  .** otherwise an
33850 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72   error will be r
33860 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53  eturned..**.** S
33870 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 6c 6f 61  ee also the [loa
33880 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 53 51  d_extension() SQ
33890 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2f 0a  L function]..*/.
338a0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
338b0 71 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65  qlite3_load_exte
338c0 6e 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33  nsion(.  sqlite3
338d0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
338e0 2a 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e  * Load the exten
338f0 73 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64  sion into this d
33900 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33910 6f 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  on */.  const ch
33920 61 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a  ar *zFile,    /*
33930 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61   Name of the sha
33940 72 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74  red library cont
33950 61 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e  aining extension
33960 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
33970 20 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45   *zProc,    /* E
33980 6e 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72  ntry point.  Der
33990 69 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20  ived from zFile 
339a0 69 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a  if 0 */.  char *
339b0 2a 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20  *pzErrMsg       
339c0 2f 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73  /* Put error mes
339d0 73 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74  sage here if not
339e0 20 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   0 */.);../*.** 
339f0 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
33a00 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
33a10 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a  nsion Loading.**
33a20 0a 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74  .** ^So as not t
33a30 6f 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20  o open security 
33a40 68 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61  holes in older a
33a50 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
33a60 20 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72   are.** unprepar
33a70 65 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20  ed to deal with 
33a80 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
33a90 67 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e  g, and as a mean
33aa0 73 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a  s of disabling.*
33ab0 2a 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64  * extension load
33ac0 69 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61  ing while evalua
33ad0 74 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65  ting user-entere
33ae0 64 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f  d SQL, the follo
33af0 77 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70  wing API.** is p
33b00 72 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20  rovided to turn 
33b10 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61  the [sqlite3_loa
33b20 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d  d_extension()] m
33b30 65 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20  echanism on and 
33b40 6f 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65  off..**.** ^Exte
33b50 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73  nsion loading is
33b60 20 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e   off by default.
33b70 20 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36   See ticket #186
33b80 33 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20  3..** ^Call the 
33b90 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
33ba0 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20  oad_extension() 
33bb0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f  routine with ono
33bc0 66 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e  ff==1.** to turn
33bd0 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
33be0 6e 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69  ng on and call i
33bf0 74 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20  t with onoff==0 
33c00 74 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61  to turn.** it ba
33c10 63 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f  ck off again..*/
33c20 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
33c30 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c  sqlite3_enable_l
33c40 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 73 71  oad_extension(sq
33c50 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e 74 20 6f  lite3 *db, int o
33c60 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
33c70 50 49 33 52 45 46 3a 20 41 75 74 6f 6d 61 74 69  PI3REF: Automati
33c80 63 61 6c 6c 79 20 4c 6f 61 64 20 53 74 61 74 69  cally Load Stati
33c90 63 61 6c 6c 79 20 4c 69 6e 6b 65 64 20 45 78 74  cally Linked Ext
33ca0 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  ensions.**.** ^T
33cb0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
33cc0 75 73 65 73 20 74 68 65 20 78 45 6e 74 72 79 50  uses the xEntryP
33cd0 6f 69 6e 74 28 29 20 66 75 6e 63 74 69 6f 6e 20  oint() function 
33ce0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 66 6f  to be invoked fo
33cf0 72 0a 2a 2a 20 65 61 63 68 20 6e 65 77 20 5b 64  r.** each new [d
33d00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
33d10 6f 6e 5d 20 74 68 61 74 20 69 73 20 63 72 65 61  on] that is crea
33d20 74 65 64 2e 20 20 54 68 65 20 69 64 65 61 20 68  ted.  The idea h
33d30 65 72 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 78  ere is that.** x
33d40 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 69 73 20  EntryPoint() is 
33d50 74 68 65 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  the entry point 
33d60 66 6f 72 20 61 20 73 74 61 74 69 63 61 6c 6c 79  for a statically
33d70 20 6c 69 6e 6b 65 64 20 53 51 4c 69 74 65 20 65   linked SQLite e
33d80 78 74 65 6e 73 69 6f 6e 0a 2a 2a 20 74 68 61 74  xtension.** that
33d90 20 69 73 20 74 6f 20 62 65 20 61 75 74 6f 6d 61   is to be automa
33da0 74 69 63 61 6c 6c 79 20 6c 6f 61 64 65 64 20 69  tically loaded i
33db0 6e 74 6f 20 61 6c 6c 20 6e 65 77 20 64 61 74 61  nto all new data
33dc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
33dd0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 6e 20 74  ..**.** ^(Even t
33de0 68 6f 75 67 68 20 74 68 65 20 66 75 6e 63 74 69  hough the functi
33df0 6f 6e 20 70 72 6f 74 6f 74 79 70 65 20 73 68 6f  on prototype sho
33e00 77 73 20 74 68 61 74 20 78 45 6e 74 72 79 50 6f  ws that xEntryPo
33e10 69 6e 74 28 29 20 74 61 6b 65 73 0a 2a 2a 20 6e  int() takes.** n
33e20 6f 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20  o arguments and 
33e30 72 65 74 75 72 6e 73 20 76 6f 69 64 2c 20 53 51  returns void, SQ
33e40 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 78 45 6e  Lite invokes xEn
33e50 74 72 79 50 6f 69 6e 74 28 29 20 77 69 74 68 20  tryPoint() with 
33e60 74 68 72 65 65 0a 2a 2a 20 61 72 67 75 6d 65 6e  three.** argumen
33e70 74 73 20 61 6e 64 20 65 78 70 65 63 74 73 20 61  ts and expects a
33e80 6e 64 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  nd integer resul
33e90 74 20 61 73 20 69 66 20 74 68 65 20 73 69 67 6e  t as if the sign
33ea0 61 74 75 72 65 20 6f 66 20 74 68 65 0a 2a 2a 20  ature of the.** 
33eb0 65 6e 74 72 79 20 70 6f 69 6e 74 20 77 68 65 72  entry point wher
33ec0 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  e as follows:.**
33ed0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
33ee0 3c 70 72 65 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20  <pre>.** &nbsp; 
33ef0 20 69 6e 74 20 78 45 6e 74 72 79 50 6f 69 6e 74   int xEntryPoint
33f00 28 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 73  (.** &nbsp;    s
33f10 71 6c 69 74 65 33 20 2a 64 62 2c 0a 2a 2a 20 26  qlite3 *db,.** &
33f20 6e 62 73 70 3b 20 20 20 20 63 6f 6e 73 74 20 63  nbsp;    const c
33f30 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73 67 2c 0a  har **pzErrMsg,.
33f40 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e  ** &nbsp;    con
33f50 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
33f60 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65 73 20 2a  3_api_routines *
33f70 70 54 68 75 6e 6b 0a 2a 2a 20 26 6e 62 73 70 3b  pThunk.** &nbsp;
33f80 20 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f    );.** </pre></
33f90 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
33fa0 0a 2a 2a 20 49 66 20 74 68 65 20 78 45 6e 74 72  .** If the xEntr
33fb0 79 50 6f 69 6e 74 20 72 6f 75 74 69 6e 65 20 65  yPoint routine e
33fc0 6e 63 6f 75 6e 74 65 72 73 20 61 6e 20 65 72 72  ncounters an err
33fd0 6f 72 2c 20 69 74 20 73 68 6f 75 6c 64 20 6d 61  or, it should ma
33fe0 6b 65 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a 20  ke *pzErrMsg.** 
33ff0 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 70 70 72  point to an appr
34000 6f 70 72 69 61 74 65 20 65 72 72 6f 72 20 6d 65  opriate error me
34010 73 73 61 67 65 20 28 6f 62 74 61 69 6e 65 64 20  ssage (obtained 
34020 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70  from [sqlite3_mp
34030 72 69 6e 74 66 28 29 5d 29 0a 2a 2a 20 61 6e 64  rintf()]).** and
34040 20 72 65 74 75 72 6e 20 61 6e 20 61 70 70 72 6f   return an appro
34050 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f  priate [error co
34060 64 65 5d 2e 20 20 5e 53 51 4c 69 74 65 20 65 6e  de].  ^SQLite en
34070 73 75 72 65 73 20 74 68 61 74 20 2a 70 7a 45 72  sures that *pzEr
34080 72 4d 73 67 0a 2a 2a 20 69 73 20 4e 55 4c 4c 20  rMsg.** is NULL 
34090 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e 67 20 74  before calling t
340a0 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  he xEntryPoint()
340b0 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
340c0 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71 6c 69 74  invoke.** [sqlit
340d0 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 2a 70  e3_free()] on *p
340e0 7a 45 72 72 4d 73 67 20 61 66 74 65 72 20 78 45  zErrMsg after xE
340f0 6e 74 72 79 50 6f 69 6e 74 28 29 20 72 65 74 75  ntryPoint() retu
34100 72 6e 73 2e 20 20 5e 49 66 20 61 6e 79 0a 2a 2a  rns.  ^If any.**
34110 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 72   xEntryPoint() r
34120 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2c  eturns an error,
34130 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
34140 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
34150 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a 20 6f 72  open16()],.** or
34160 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
34170 32 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 70  2()] call that p
34180 72 6f 76 6f 6b 65 64 20 74 68 65 20 78 45 6e 74  rovoked the xEnt
34190 72 79 50 6f 69 6e 74 28 29 20 77 69 6c 6c 20 66  ryPoint() will f
341a0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ail..**.** ^Call
341b0 69 6e 67 20 73 71 6c 69 74 65 33 5f 61 75 74 6f  ing sqlite3_auto
341c0 5f 65 78 74 65 6e 73 69 6f 6e 28 58 29 20 77 69  _extension(X) wi
341d0 74 68 20 61 6e 20 65 6e 74 72 79 20 70 6f 69 6e  th an entry poin
341e0 74 20 58 20 74 68 61 74 20 69 73 20 61 6c 72 65  t X that is alre
341f0 61 64 79 0a 2a 2a 20 6f 6e 20 74 68 65 20 6c 69  ady.** on the li
34200 73 74 20 6f 66 20 61 75 74 6f 6d 61 74 69 63 20  st of automatic 
34210 65 78 74 65 6e 73 69 6f 6e 73 20 69 73 20 61 20  extensions is a 
34220 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 20  harmless no-op. 
34230 5e 4e 6f 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a  ^No entry point.
34240 2a 2a 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65  ** will be calle
34250 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
34260 20 66 6f 72 20 65 61 63 68 20 64 61 74 61 62 61   for each databa
34270 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
34280 61 74 20 69 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  at is opened..**
34290 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
342a0 71 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74  qlite3_reset_aut
342b0 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 2e 0a  o_extension()]..
342c0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
342d0 74 20 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65  t sqlite3_auto_e
342e0 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 20 28 2a  xtension(void (*
342f0 78 45 6e 74 72 79 50 6f 69 6e 74 29 28 76 6f 69  xEntryPoint)(voi
34300 64 29 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d));../*.** CAPI
34310 33 52 45 46 3a 20 52 65 73 65 74 20 41 75 74 6f  3REF: Reset Auto
34320 6d 61 74 69 63 20 45 78 74 65 6e 73 69 6f 6e 20  matic Extension 
34330 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 54  Loading.**.** ^T
34340 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 64 69  his interface di
34350 73 61 62 6c 65 73 20 61 6c 6c 20 61 75 74 6f 6d  sables all autom
34360 61 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20  atic extensions 
34370 70 72 65 76 69 6f 75 73 6c 79 0a 2a 2a 20 72 65  previously.** re
34380 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 5b  gistered using [
34390 73 71 6c 69 74 65 33 5f 61 75 74 6f 5f 65 78 74  sqlite3_auto_ext
343a0 65 6e 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 53 51  ension()]..*/.SQ
343b0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
343c0 6c 69 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f  lite3_reset_auto
343d0 5f 65 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29  _extension(void)
343e0 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74  ;../*.** The int
343f0 65 72 66 61 63 65 20 74 6f 20 74 68 65 20 76 69  erface to the vi
34400 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
34410 61 6e 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74  anism is current
34420 6c 79 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a  ly considered.**
34430 20 74 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e   to be experimen
34440 74 61 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66  tal.  The interf
34450 61 63 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65  ace might change
34460 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65   in incompatible
34470 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69   ways..** If thi
34480 73 20 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66  s is a problem f
34490 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75  or you, do not u
344a0 73 65 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  se the interface
344b0 20 61 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a   at this time..*
344c0 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69  *.** When the vi
344d0 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68  rtual-table mech
344e0 61 6e 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73  anism stabilizes
344f0 2c 20 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72  , we will declar
34500 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61  e the.** interfa
34510 63 65 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72  ce fixed, suppor
34520 74 20 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c  t it indefinitel
34530 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68  y, and remove th
34540 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a  is comment..*/..
34550 2f 2a 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73  /*.** Structures
34560 20 75 73 65 64 20 62 79 20 74 68 65 20 76 69 72   used by the vir
34570 74 75 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72  tual table inter
34580 66 61 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20  face.*/.typedef 
34590 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
345a0 74 61 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62  tab sqlite3_vtab
345b0 3b 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  ;.typedef struct
345c0 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
345d0 6e 66 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  nfo sqlite3_inde
345e0 78 5f 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20  x_info;.typedef 
345f0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
34600 74 61 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74  tab_cursor sqlit
34610 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a  e3_vtab_cursor;.
34620 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
34630 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71  qlite3_module sq
34640 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f  lite3_module;../
34650 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
34660 69 72 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a  irtual Table Obj
34670 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
34680 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
34690 7b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  {virtual table m
346a0 6f 64 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69  odule}.**.** Thi
346b0 73 20 73 74 72 75 63 74 75 72 65 2c 20 73 6f 6d  s structure, som
346c0 65 74 69 6d 65 73 20 63 61 6c 6c 65 64 20 61 20  etimes called a 
346d0 61 20 22 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a "virtual table
346e0 20 6d 6f 64 75 6c 65 22 2c 20 0a 2a 2a 20 64 65   module", .** de
346f0 66 69 6e 65 73 20 74 68 65 20 69 6d 70 6c 65 6d  fines the implem
34700 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 20 5b 76  entation of a [v
34710 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 20  irtual tables]. 
34720 20 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63 74   .** This struct
34730 75 72 65 20 63 6f 6e 73 69 73 74 73 20 6d 6f 73  ure consists mos
34740 74 6c 79 20 6f 66 20 6d 65 74 68 6f 64 73 20 66  tly of methods f
34750 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a  or the module..*
34760 2a 0a 2a 2a 20 5e 41 20 76 69 72 74 75 61 6c 20  *.** ^A virtual 
34770 74 61 62 6c 65 20 6d 6f 64 75 6c 65 20 69 73 20  table module is 
34780 63 72 65 61 74 65 64 20 62 79 20 66 69 6c 6c 69  created by filli
34790 6e 67 20 69 6e 20 61 20 70 65 72 73 69 73 74 65  ng in a persiste
347a0 6e 74 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  nt.** instance o
347b0 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72 65  f this structure
347c0 20 61 6e 64 20 70 61 73 73 69 6e 67 20 61 20 70   and passing a p
347d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 61 74 20 69  ointer to that i
347e0 6e 73 74 61 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73  nstance.** to [s
347f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
34800 64 75 6c 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  dule()] or [sqli
34810 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c  te3_create_modul
34820 65 5f 76 32 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  e_v2()]..** ^The
34830 20 72 65 67 69 73 74 72 61 74 69 6f 6e 20 72 65   registration re
34840 6d 61 69 6e 73 20 76 61 6c 69 64 20 75 6e 74 69  mains valid unti
34850 6c 20 69 74 20 69 73 20 72 65 70 6c 61 63 65 64  l it is replaced
34860 20 62 79 20 61 20 64 69 66 66 65 72 65 6e 74 0a   by a different.
34870 2a 2a 20 6d 6f 64 75 6c 65 20 6f 72 20 75 6e 74  ** module or unt
34880 69 6c 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  il the [database
34890 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f   connection] clo
348a0 73 65 73 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  ses.  The conten
348b0 74 0a 2a 2a 20 6f 66 20 74 68 69 73 20 73 74 72  t.** of this str
348c0 75 63 74 75 72 65 20 6d 75 73 74 20 6e 6f 74 20  ucture must not 
348d0 63 68 61 6e 67 65 20 77 68 69 6c 65 20 69 74 20  change while it 
348e0 69 73 20 72 65 67 69 73 74 65 72 65 64 20 77 69  is registered wi
348f0 74 68 0a 2a 2a 20 61 6e 79 20 64 61 74 61 62 61  th.** any databa
34900 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a  se connection..*
34910 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  /.struct sqlite3
34920 5f 6d 6f 64 75 6c 65 20 7b 0a 20 20 69 6e 74 20  _module {.  int 
34930 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
34940 28 2a 78 43 72 65 61 74 65 29 28 73 71 6c 69 74  (*xCreate)(sqlit
34950 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c  e3*, void *pAux,
34960 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
34970 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20  int argc, const 
34980 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76  char *const*argv
34990 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
349a0 20 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a   sqlite3_vtab **
349b0 70 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b  ppVTab, char**);
349c0 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6e 6e 65 63  .  int (*xConnec
349d0 74 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  t)(sqlite3*, voi
349e0 64 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20  d *pAux,.       
349f0 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63          int argc
34a00 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f  , const char *co
34a10 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20  nst*argv,.      
34a20 20 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33           sqlite3
34a30 5f 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20  _vtab **ppVTab, 
34a40 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  char**);.  int (
34a50 2a 78 42 65 73 74 49 6e 64 65 78 29 28 73 71 6c  *xBestIndex)(sql
34a60 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
34a70 2c 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  , sqlite3_index_
34a80 69 6e 66 6f 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  info*);.  int (*
34a90 78 44 69 73 63 6f 6e 6e 65 63 74 29 28 73 71 6c  xDisconnect)(sql
34aa0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
34ab0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 73 74  );.  int (*xDest
34ac0 72 6f 79 29 28 73 71 6c 69 74 65 33 5f 76 74 61  roy)(sqlite3_vta
34ad0 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74  b *pVTab);.  int
34ae0 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65   (*xOpen)(sqlite
34af0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73  3_vtab *pVTab, s
34b00 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
34b10 6f 72 20 2a 2a 70 70 43 75 72 73 6f 72 29 3b 0a  or **ppCursor);.
34b20 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
34b30 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
34b40 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sor*);.  int (*x
34b50 46 69 6c 74 65 72 29 28 73 71 6c 69 74 65 33 5f  Filter)(sqlite3_
34b60 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 69 6e  vtab_cursor*, in
34b70 74 20 69 64 78 4e 75 6d 2c 20 63 6f 6e 73 74 20  t idxNum, const 
34b80 63 68 61 72 20 2a 69 64 78 53 74 72 2c 0a 20 20  char *idxStr,.  
34b90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
34ba0 74 20 61 72 67 63 2c 20 73 71 6c 69 74 65 33 5f  t argc, sqlite3_
34bb0 76 61 6c 75 65 20 2a 2a 61 72 67 76 29 3b 0a 20  value **argv);. 
34bc0 20 69 6e 74 20 28 2a 78 4e 65 78 74 29 28 73 71   int (*xNext)(sq
34bd0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
34be0 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 45 6f  r*);.  int (*xEo
34bf0 66 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  f)(sqlite3_vtab_
34c00 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e 74 20  cursor*);.  int 
34c10 28 2a 78 43 6f 6c 75 6d 6e 29 28 73 71 6c 69 74  (*xColumn)(sqlit
34c20 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c  e3_vtab_cursor*,
34c30 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
34c40 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
34c50 2a 78 52 6f 77 69 64 29 28 73 71 6c 69 74 65 33  *xRowid)(sqlite3
34c60 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73  _vtab_cursor*, s
34c70 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 52  qlite3_int64 *pR
34c80 6f 77 69 64 29 3b 0a 20 20 69 6e 74 20 28 2a 78  owid);.  int (*x
34c90 55 70 64 61 74 65 29 28 73 71 6c 69 74 65 33 5f  Update)(sqlite3_
34ca0 76 74 61 62 20 2a 2c 20 69 6e 74 2c 20 73 71 6c  vtab *, int, sql
34cb0 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 2c 20 73  ite3_value **, s
34cc0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 29 3b  qlite3_int64 *);
34cd0 0a 20 20 69 6e 74 20 28 2a 78 42 65 67 69 6e 29  .  int (*xBegin)
34ce0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
34cf0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
34d00 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 76 74  Sync)(sqlite3_vt
34d10 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
34d20 74 20 28 2a 78 43 6f 6d 6d 69 74 29 28 73 71 6c  t (*xCommit)(sql
34d30 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
34d40 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c  );.  int (*xRoll
34d50 62 61 63 6b 29 28 73 71 6c 69 74 65 33 5f 76 74  back)(sqlite3_vt
34d60 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e  ab *pVTab);.  in
34d70 74 20 28 2a 78 46 69 6e 64 46 75 6e 63 74 69 6f  t (*xFindFunctio
34d80 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  n)(sqlite3_vtab 
34d90 2a 70 56 74 61 62 2c 20 69 6e 74 20 6e 41 72 67  *pVtab, int nArg
34da0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
34db0 61 6d 65 2c 0a 20 20 20 20 20 20 20 20 20 20 20  ame,.           
34dc0 20 20 20 20 20 20 20 20 20 20 20 20 76 6f 69 64              void
34dd0 20 28 2a 2a 70 78 46 75 6e 63 29 28 73 71 6c 69   (**pxFunc)(sqli
34de0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
34df0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
34e00 29 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20  ),.             
34e10 20 20 20 20 20 20 20 20 20 20 76 6f 69 64 20 2a            void *
34e20 2a 70 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28  *ppArg);.  int (
34e30 2a 78 52 65 6e 61 6d 65 29 28 73 71 6c 69 74 65  *xRename)(sqlite
34e40 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 63  3_vtab *pVtab, c
34e50 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 65 77 29  onst char *zNew)
34e60 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ;.};../*.** CAPI
34e70 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
34e80 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66  ble Indexing Inf
34e90 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57  ormation.** KEYW
34ea0 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e  ORDS: sqlite3_in
34eb0 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54  dex_info.**.** T
34ec0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  he sqlite3_index
34ed0 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20  _info structure 
34ee0 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63  and its substruc
34ef0 74 75 72 65 73 20 69 73 20 75 73 65 64 20 61 73  tures is used as
34f00 20 70 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65 20   part.** of the 
34f10 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20  [virtual table] 
34f20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
34f30 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  pass information
34f40 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76   into and receiv
34f50 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d  e the reply from
34f60 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78   the [xBestIndex
34f70 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61  ].** method of a
34f80 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
34f90 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69  module].  The fi
34fa0 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70  elds under **Inp
34fb0 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a  uts** are the.**
34fc0 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74   inputs to xBest
34fd0 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65  Index and are re
34fe0 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49  ad-only.  xBestI
34ff0 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73  ndex inserts its
35000 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
35010 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a   the **Outputs**
35020 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e   fields..**.** ^
35030 28 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74  (The aConstraint
35040 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73  [] array records
35050 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
35060 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65  nstraints of the
35070 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   form:.**.** <bl
35080 6f 63 6b 71 75 6f 74 65 3e 63 6f 6c 75 6d 6e 20  ockquote>column 
35090 4f 50 20 65 78 70 72 3c 2f 62 6c 6f 63 6b 71 75  OP expr</blockqu
350a0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65  ote>.**.** where
350b0 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20   OP is =, &lt;, 
350c0 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20  &lt;=, &gt;, or 
350d0 26 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20  &gt;=.)^  ^(The 
350e0 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61  particular opera
350f0 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64  tor is.** stored
35100 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b   in aConstraint[
35110 5d 2e 6f 70 20 75 73 69 6e 67 20 6f 6e 65 20 6f  ].op using one o
35120 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
35130 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
35140 54 5f 45 51 20 7c 20 53 51 4c 49 54 45 5f 49 4e  T_EQ | SQLITE_IN
35150 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 20  DEX_CONSTRAINT_ 
35160 76 61 6c 75 65 73 5d 2e 29 5e 0a 2a 2a 20 5e 28  values].)^.** ^(
35170 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  The index of the
35180 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65   column is store
35190 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61  d in.** aConstra
351a0 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e  int[].iColumn.)^
351b0 20 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b    ^(aConstraint[
351c0 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45  ].usable is TRUE
351d0 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20   if the.** expr 
351e0 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  on the right-han
351f0 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76  d side can be ev
35200 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75  aluated (and thu
35210 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  s the constraint
35220 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61  .** is usable) a
35230 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63  nd false if it c
35240 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  annot.)^.**.** ^
35250 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75  The optimizer au
35260 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65  tomatically inve
35270 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65  rts terms of the
35280 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63   form "expr OP c
35290 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61  olumn".** and ma
352a0 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69  kes other simpli
352b0 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65  fications to the
352c0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e   WHERE clause in
352d0 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a   an attempt to.*
352e0 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48  * get as many WH
352f0 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73  ERE clause terms
35300 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73   into the form s
35310 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f  hown above as po
35320 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20  ssible..** ^The 
35330 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
35340 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ray only reports
35350 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
35360 72 6d 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  rms that are.** 
35370 72 65 6c 65 76 61 6e 74 20 74 6f 20 74 68 65 20  relevant to the 
35380 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75  particular virtu
35390 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71  al table being q
353a0 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ueried..**.** ^I
353b0 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
353c0 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
353d0 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69  ause is stored i
353e0 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a  n aOrderBy[]..**
353f0 20 5e 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61   ^Each term of a
35400 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20  OrderBy records 
35410 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  a column of the 
35420 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e  ORDER BY clause.
35430 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73  .**.** The [xBes
35440 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d  tIndex] method m
35450 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72  ust fill aConstr
35460 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68  aintUsage[] with
35470 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
35480 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d  about what param
35490 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f  eters to pass to
354a0 20 78 46 69 6c 74 65 72 2e 20 20 5e 49 66 20 61   xFilter.  ^If a
354b0 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a  rgvIndex>0 then.
354c0 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  ** the right-han
354d0 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f  d side of the co
354e0 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e  rresponding aCon
354f0 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61  straint[] is eva
35500 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65  luated.** and be
35510 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e  comes the argvIn
35520 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20  dex-th entry in 
35530 61 72 67 76 2e 20 20 5e 28 49 66 20 61 43 6f 6e  argv.  ^(If aCon
35540 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f  straintUsage[].o
35550 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20  mit.** is true, 
35560 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61  then the constra
35570 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74  int is assumed t
35580 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c  o be fully handl
35590 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72  ed by the.** vir
355a0 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20 69  tual table and i
355b0 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61 67  s not checked ag
355c0 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 29 5e  ain by SQLite.)^
355d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64 78 4e  .**.** ^The idxN
355e0 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76 61  um and idxPtr va
355f0 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64 65  lues are recorde
35600 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e 74  d and passed int
35610 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74 65  o the.** [xFilte
35620 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e 5b  r] method..** ^[
35630 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
35640 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65 20  is used to free 
35650 69 64 78 50 74 72 20 69 66 20 61 6e 64 20 6f 6e  idxPtr if and on
35660 6c 79 20 69 66 0a 2a 2a 20 6e 65 65 64 54 6f 46  ly if.** needToF
35670 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72 75  reeIdxPtr is tru
35680 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 72  e..**.** ^The or
35690 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d 65  derByConsumed me
356a0 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74 20  ans that output 
356b0 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f 5b  from [xFilter]/[
356c0 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63 75  xNext] will occu
356d0 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72 72  r in.** the corr
356e0 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61 74  ect order to sat
356f0 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20 42  isfy the ORDER B
35700 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61 74  Y clause so that
35710 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a 20   no separate.** 
35720 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73 20  sorting step is 
35730 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
35740 5e 54 68 65 20 65 73 74 69 6d 61 74 65 64 43 6f  ^The estimatedCo
35750 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20 65  st value is an e
35760 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20 63  stimate of the c
35770 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68 65  ost of doing the
35780 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20 6c  .** particular l
35790 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20 73  ookup.  A full s
357a0 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20 77  can of a table w
357b0 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73 68  ith N entries sh
357c0 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20 63  ould have.** a c
357d0 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69 6e  ost of N.  A bin
357e0 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61 20  ary search of a 
357f0 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72 69  table of N entri
35800 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20 61  es should have a
35810 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70 72  .** cost of appr
35820 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e 29  oximately log(N)
35830 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
35840 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 7b  te3_index_info {
35850 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f 0a  .  /* Inputs */.
35860 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69 6e    int nConstrain
35870 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t;           /* 
35880 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69 65  Number of entrie
35890 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  s in aConstraint
358a0 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
358b0 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74  ite3_index_const
358c0 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e 74  raint {.     int
358d0 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20   iColumn;       
358e0 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e         /* Column
358f0 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73 69   on left-hand si
35900 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e 74  de of constraint
35910 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
35920 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20 20  d char op;      
35930 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e 74     /* Constraint
35940 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20 20   operator */.   
35950 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20    unsigned char 
35960 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20 54  usable;     /* T
35970 72 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e 73  rue if this cons
35980 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c 65  traint is usable
35990 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54 65   */.     int iTe
359a0 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20 20  rmOffset;       
359b0 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65 72     /* Used inter
359c0 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e 64  nally - xBestInd
359d0 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72 65  ex should ignore
359e0 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74 72   */.  } *aConstr
359f0 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20  aint;           
35a00 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48 45   /* Table of WHE
35a10 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74 72  RE clause constr
35a20 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e  aints */.  int n
35a30 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20 20  OrderBy;        
35a40 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
35a50 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65 20  of terms in the 
35a60 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
35a70 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
35a80 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72 62  te3_index_orderb
35a90 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43 6f  y {.     int iCo
35aa0 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20 20  lumn;           
35ab0 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75 6d     /* Column num
35ac0 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69  ber */.     unsi
35ad0 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b 20  gned char desc; 
35ae0 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66 6f        /* True fo
35af0 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20 66  r DESC.  False f
35b00 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20 2a  or ASC. */.  } *
35b10 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20  aOrderBy;       
35b20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20 4f          /* The O
35b30 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20 2a  RDER BY clause *
35b40 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20 2a  /.  /* Outputs *
35b50 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69 74  /.  struct sqlit
35b60 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72 61  e3_index_constra
35b70 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20 20  int_usage {.    
35b80 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20 20  int argvIndex;  
35b90 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20 3e           /* if >
35ba0 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  0, constraint is
35bb0 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74 6f   part of argv to
35bc0 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20 20   xFilter */.    
35bd0 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 6d  unsigned char om
35be0 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20 6e  it;      /* Do n
35bf0 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20 66  ot code a test f
35c00 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61 69  or this constrai
35c10 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73  nt */.  } *aCons
35c20 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20 69  traintUsage;.  i
35c30 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20 20  nt idxNum;      
35c40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
35c50 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 65 6e  ber used to iden
35c60 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 20 2a  tify the index *
35c70 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74 72  /.  char *idxStr
35c80 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ;              /
35c90 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69 62  * String, possib
35ca0 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
35cb0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 20   sqlite3_malloc 
35cc0 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f 46  */.  int needToF
35cd0 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 20 20  reeIdxStr;      
35ce0 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 20 75  /* Free idxStr u
35cf0 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  sing sqlite3_fre
35d00 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a 20  e() if true */. 
35d10 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e 73   int orderByCons
35d20 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20 54  umed;       /* T
35d30 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 69 73  rue if output is
35d40 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65 64   already ordered
35d50 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73 74   */.  double est
35d60 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20 20  imatedCost;     
35d70 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63 6f   /* Estimated co
35d80 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73  st of using this
35d90 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 0a 2f 2a   index */.};../*
35da0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69  .** CAPI3REF: Vi
35db0 72 74 75 61 6c 20 54 61 62 6c 65 20 43 6f 6e 73  rtual Table Cons
35dc0 74 72 61 69 6e 74 20 4f 70 65 72 61 74 6f 72 20  traint Operator 
35dd0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  Codes.**.** Thes
35de0 65 20 6d 61 63 72 6f 73 20 64 65 66 69 6e 65 64  e macros defined
35df0 20 74 68 65 20 61 6c 6c 6f 77 65 64 20 76 61 6c   the allowed val
35e00 75 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  ues for the.** [
35e10 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e  sqlite3_index_in
35e20 66 6f 5d 2e 61 43 6f 6e 73 74 72 61 69 6e 74 5b  fo].aConstraint[
35e30 5d 2e 6f 70 20 66 69 65 6c 64 2e 20 20 45 61 63  ].op field.  Eac
35e40 68 20 76 61 6c 75 65 20 72 65 70 72 65 73 65 6e  h value represen
35e50 74 73 0a 2a 2a 20 61 6e 20 6f 70 65 72 61 74 6f  ts.** an operato
35e60 72 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f  r that is part o
35e70 66 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 74  f a constraint t
35e80 65 72 6d 20 69 6e 20 74 68 65 20 77 48 45 52 45  erm in the wHERE
35e90 20 63 6c 61 75 73 65 20 6f 66 0a 2a 2a 20 61 20   clause of.** a 
35ea0 71 75 65 72 79 20 74 68 61 74 20 75 73 65 73 20  query that uses 
35eb0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
35ec0 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
35ed0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
35ee0 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23 64  RAINT_EQ    2.#d
35ef0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
35f00 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 54  EX_CONSTRAINT_GT
35f10 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
35f20 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
35f30 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23 64  RAINT_LE    8.#d
35f40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
35f50 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 54  EX_CONSTRAINT_LT
35f60 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53      16.#define S
35f70 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
35f80 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32 0a  TRAINT_GE    32.
35f90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
35fa0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
35fb0 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a 20  MATCH 64../*.** 
35fc0 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
35fd0 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61 62  er A Virtual Tab
35fe0 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le Implementatio
35ff0 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  n.**.** ^These r
36000 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
36010 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20 6e   to register a n
36020 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ew [virtual tabl
36030 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e 0a  e module] name..
36040 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65 73  ** ^Module names
36050 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74 65   must be registe
36060 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63 72  red before.** cr
36070 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76 69  eating a new [vi
36080 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73 69  rtual table] usi
36090 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 61 6e  ng the module an
360a0 64 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20 61  d before using a
360b0 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67 20  .** preexisting 
360c0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20  [virtual table] 
360d0 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e 0a  for the module..
360e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75 6c  **.** ^The modul
360f0 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73 74  e name is regist
36100 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61 74  ered on the [dat
36110 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36120 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  ] specified.** b
36130 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
36140 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61 6d  meter.  ^The nam
36150 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20  e of the module 
36160 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  is given by the 
36170 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
36180 65 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69 72  eter.  ^The thir
36190 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
361a0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 74   pointer to.** t
361b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
361c0 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  n of the [virtua
361d0 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e  l table module].
361e0 20 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a 2a     ^The fourth.*
361f0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  * parameter is a
36200 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c 69 65  n arbitrary clie
36210 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  nt data pointer 
36220 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 74  that is passed t
36230 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20 74  hrough.** into t
36240 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64  he [xCreate] and
36250 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68   [xConnect] meth
36260 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72 74 75  ods of the virtu
36270 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 0a  al table module.
36280 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76 69  ** when a new vi
36290 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20 62  rtual table is b
362a0 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 20  e being created 
362b0 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65 64  or reinitialized
362c0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
362d0 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75  ite3_create_modu
362e0 6c 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  le_v2() interfac
362f0 65 20 68 61 73 20 61 20 66 69 66 74 68 20 70 61  e has a fifth pa
36300 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a 2a  rameter which.**
36310 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
36320 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f   a destructor fo
36330 72 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61 74  r the pClientDat
36340 61 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  a.  ^SQLite will
36350 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  .** invoke the d
36360 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69  estructor functi
36370 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f 74  on (if it is not
36380 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c 69   NULL) when SQLi
36390 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72 20  te.** no longer 
363a0 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 65 6e  needs the pClien
363b0 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 20  tData pointer.  
363c0 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20  ^The destructor 
363d0 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65 20  will also.** be 
363e0 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
363f0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  all to sqlite3_c
36400 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
36410 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 54 68 65  ) fails..** ^The
36420 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36430 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74 65  module().** inte
36440 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61 6c  rface is equival
36450 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
36460 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
36470 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a 2a  ) with a NULL.**
36480 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f 0a   destructor..*/.
36490 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
364a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f  qlite3_create_mo
364b0 64 75 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  dule(.  sqlite3 
364c0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
364d0 20 20 20 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e     /* SQLite con
364e0 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65 67 69 73  nection to regis
364f0 74 65 72 20 6d 6f 64 75 6c 65 20 77 69 74 68 20  ter module with 
36500 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
36510 2a 7a 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  *zName,         
36520 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d  /* Name of the m
36530 6f 64 75 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  odule */.  const
36540 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20   sqlite3_module 
36550 2a 70 2c 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *p,   /* Methods
36560 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 20   for the module 
36570 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 43 6c 69 65  */.  void *pClie
36580 6e 74 44 61 74 61 20 20 20 20 20 20 20 20 20 20  ntData          
36590 2f 2a 20 43 6c 69 65 6e 74 20 64 61 74 61 20 66  /* Client data f
365a0 6f 72 20 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e  or xCreate/xConn
365b0 65 63 74 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  ect */.);.SQLITE
365c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
365d0 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76  _create_module_v
365e0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
365f0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
36600 2f 2a 20 53 51 4c 69 74 65 20 63 6f 6e 6e 65 63  /* SQLite connec
36610 74 69 6f 6e 20 74 6f 20 72 65 67 69 73 74 65 72  tion to register
36620 20 6d 6f 64 75 6c 65 20 77 69 74 68 20 2a 2f 0a   module with */.
36630 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
36640 61 6d 65 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ame,         /* 
36650 4e 61 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75  Name of the modu
36660 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 73 71  le */.  const sq
36670 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 2c  lite3_module *p,
36680 20 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f     /* Methods fo
36690 72 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  r the module */.
366a0 20 20 76 6f 69 64 20 2a 70 43 6c 69 65 6e 74 44    void *pClientD
366b0 61 74 61 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  ata,         /* 
366c0 43 6c 69 65 6e 74 20 64 61 74 61 20 66 6f 72 20  Client data for 
366d0 78 43 72 65 61 74 65 2f 78 43 6f 6e 6e 65 63 74  xCreate/xConnect
366e0 20 2a 2f 0a 20 20 76 6f 69 64 28 2a 78 44 65 73   */.  void(*xDes
366f0 74 72 6f 79 29 28 76 6f 69 64 2a 29 20 20 20 20  troy)(void*)    
36700 20 2f 2a 20 4d 6f 64 75 6c 65 20 64 65 73 74 72   /* Module destr
36710 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 2a  uctor function *
36720 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
36730 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
36740 62 6c 65 20 49 6e 73 74 61 6e 63 65 20 4f 62 6a  ble Instance Obj
36750 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
36760 20 73 71 6c 69 74 65 33 5f 76 74 61 62 0a 2a 2a   sqlite3_vtab.**
36770 0a 2a 2a 20 45 76 65 72 79 20 5b 76 69 72 74 75  .** Every [virtu
36780 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
36790 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
367a0 75 73 65 73 20 61 20 73 75 62 63 6c 61 73 73 0a  uses a subclass.
367b0 2a 2a 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ** of this objec
367c0 74 20 74 6f 20 64 65 73 63 72 69 62 65 20 61 20  t to describe a 
367d0 70 61 72 74 69 63 75 6c 61 72 20 69 6e 73 74 61  particular insta
367e0 6e 63 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 76  nce.** of the [v
367f0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 20 20  irtual table].  
36800 45 61 63 68 20 73 75 62 63 6c 61 73 73 20 77 69  Each subclass wi
36810 6c 6c 0a 2a 2a 20 62 65 20 74 61 69 6c 6f 72 65  ll.** be tailore
36820 64 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  d to the specifi
36830 63 20 6e 65 65 64 73 20 6f 66 20 74 68 65 20 6d  c needs of the m
36840 6f 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  odule implementa
36850 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 20 70 75 72  tion..** The pur
36860 70 6f 73 65 20 6f 66 20 74 68 69 73 20 73 75 70  pose of this sup
36870 65 72 63 6c 61 73 73 20 69 73 20 74 6f 20 64 65  erclass is to de
36880 66 69 6e 65 20 63 65 72 74 61 69 6e 20 66 69 65  fine certain fie
36890 6c 64 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  lds that are.** 
368a0 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c 20 6d 6f  common to all mo
368b0 64 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  dule implementat
368c0 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 56 69 72  ions..**.** ^Vir
368d0 74 75 61 6c 20 74 61 62 6c 65 73 20 6d 65 74 68  tual tables meth
368e0 6f 64 73 20 63 61 6e 20 73 65 74 20 61 6e 20 65  ods can set an e
368f0 72 72 6f 72 20 6d 65 73 73 61 67 65 20 62 79 20  rror message by 
36900 61 73 73 69 67 6e 69 6e 67 20 61 0a 2a 2a 20 73  assigning a.** s
36910 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66  tring obtained f
36920 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72  rom [sqlite3_mpr
36930 69 6e 74 66 28 29 5d 20 74 6f 20 7a 45 72 72 4d  intf()] to zErrM
36940 73 67 2e 20 20 54 68 65 20 6d 65 74 68 6f 64 20  sg.  The method 
36950 73 68 6f 75 6c 64 0a 2a 2a 20 74 61 6b 65 20 63  should.** take c
36960 61 72 65 20 74 68 61 74 20 61 6e 79 20 70 72 69  are that any pri
36970 6f 72 20 73 74 72 69 6e 67 20 69 73 20 66 72 65  or string is fre
36980 65 64 20 62 79 20 61 20 63 61 6c 6c 20 74 6f 20  ed by a call to 
36990 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
369a0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 61 73 73  .** prior to ass
369b0 69 67 6e 69 6e 67 20 61 20 6e 65 77 20 73 74 72  igning a new str
369c0 69 6e 67 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20  ing to zErrMsg. 
369d0 20 5e 41 66 74 65 72 20 74 68 65 20 65 72 72 6f   ^After the erro
369e0 72 20 6d 65 73 73 61 67 65 0a 2a 2a 20 69 73 20  r message.** is 
369f0 64 65 6c 69 76 65 72 65 64 20 75 70 20 74 6f 20  delivered up to 
36a00 74 68 65 20 63 6c 69 65 6e 74 20 61 70 70 6c 69  the client appli
36a10 63 61 74 69 6f 6e 2c 20 74 68 65 20 73 74 72 69  cation, the stri
36a20 6e 67 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  ng will be autom
36a30 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 66 72 65 65  atically.** free
36a40 64 20 62 79 20 73 71 6c 69 74 65 33 5f 66 72 65  d by sqlite3_fre
36a50 65 28 29 20 61 6e 64 20 74 68 65 20 7a 45 72 72  e() and the zErr
36a60 4d 73 67 20 66 69 65 6c 64 20 77 69 6c 6c 20 62  Msg field will b
36a70 65 20 7a 65 72 6f 65 64 2e 0a 2a 2f 0a 73 74 72  e zeroed..*/.str
36a80 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
36a90 20 7b 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74   {.  const sqlit
36aa0 65 33 5f 6d 6f 64 75 6c 65 20 2a 70 4d 6f 64 75  e3_module *pModu
36ab0 6c 65 3b 20 20 2f 2a 20 54 68 65 20 6d 6f 64 75  le;  /* The modu
36ac0 6c 65 20 66 6f 72 20 74 68 69 73 20 76 69 72 74  le for this virt
36ad0 75 61 6c 20 74 61 62 6c 65 20 2a 2f 0a 20 20 69  ual table */.  i
36ae0 6e 74 20 6e 52 65 66 3b 20 20 20 20 20 20 20 20  nt nRef;        
36af0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
36b00 2a 20 4e 4f 20 4c 4f 4e 47 45 52 20 55 53 45 44  * NO LONGER USED
36b10 20 2a 2f 0a 20 20 63 68 61 72 20 2a 7a 45 72 72   */.  char *zErr
36b20 4d 73 67 3b 20 20 20 20 20 20 20 20 20 20 20 20  Msg;            
36b30 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
36b40 65 73 73 61 67 65 20 66 72 6f 6d 20 73 71 6c 69  essage from sqli
36b50 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 2a 2f  te3_mprintf() */
36b60 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61  .  /* Virtual ta
36b70 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
36b80 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c  ons will typical
36b90 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ly add additiona
36ba0 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a  l fields */.};..
36bb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36bc0 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 75  Virtual Table Cu
36bd0 72 73 6f 72 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  rsor Object.** K
36be0 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
36bf0 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 7b 76 69  _vtab_cursor {vi
36c00 72 74 75 61 6c 20 74 61 62 6c 65 20 63 75 72 73  rtual table curs
36c10 6f 72 7d 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20  or}.**.** Every 
36c20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
36c30 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e 74  odule] implement
36c40 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75 62  ation uses a sub
36c50 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
36c60 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 72 75 63 74  following struct
36c70 75 72 65 20 74 6f 20 64 65 73 63 72 69 62 65 20  ure to describe 
36c80 63 75 72 73 6f 72 73 20 74 68 61 74 20 70 6f 69  cursors that poi
36c90 6e 74 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 5b  nt into the.** [
36ca0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 61  virtual table] a
36cb0 6e 64 20 61 72 65 20 75 73 65 64 0a 2a 2a 20 74  nd are used.** t
36cc0 6f 20 6c 6f 6f 70 20 74 68 72 6f 75 67 68 20 74  o loop through t
36cd0 68 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  he virtual table
36ce0 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65 20 63  .  Cursors are c
36cf0 72 65 61 74 65 64 20 75 73 69 6e 67 20 74 68 65  reated using the
36d00 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64  .** [sqlite3_mod
36d10 75 6c 65 2e 78 4f 70 65 6e 20 7c 20 78 4f 70 65  ule.xOpen | xOpe
36d20 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  n] method of the
36d30 20 6d 6f 64 75 6c 65 20 61 6e 64 20 61 72 65 20   module and are 
36d40 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20 62 79 20  destroyed.** by 
36d50 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 6f 64  the [sqlite3_mod
36d60 75 6c 65 2e 78 43 6c 6f 73 65 20 7c 20 78 43 6c  ule.xClose | xCl
36d70 6f 73 65 5d 20 6d 65 74 68 6f 64 2e 20 20 43 75  ose] method.  Cu
36d80 72 73 6f 72 73 20 61 72 65 20 75 73 65 64 0a 2a  rsors are used.*
36d90 2a 20 62 79 20 74 68 65 20 5b 78 46 69 6c 74 65  * by the [xFilte
36da0 72 5d 2c 20 5b 78 4e 65 78 74 5d 2c 20 5b 78 45  r], [xNext], [xE
36db0 6f 66 5d 2c 20 5b 78 43 6f 6c 75 6d 6e 5d 2c 20  of], [xColumn], 
36dc0 61 6e 64 20 5b 78 52 6f 77 69 64 5d 20 6d 65 74  and [xRowid] met
36dd0 68 6f 64 73 0a 2a 2a 20 6f 66 20 74 68 65 20 6d  hods.** of the m
36de0 6f 64 75 6c 65 2e 20 20 45 61 63 68 20 6d 6f 64  odule.  Each mod
36df0 75 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ule implementati
36e00 6f 6e 20 77 69 6c 6c 20 64 65 66 69 6e 65 0a 2a  on will define.*
36e10 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
36e20 20 61 20 63 75 72 73 6f 72 20 73 74 72 75 63 74   a cursor struct
36e30 75 72 65 20 74 6f 20 73 75 69 74 20 69 74 73 20  ure to suit its 
36e40 6f 77 6e 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  own needs..**.**
36e50 20 54 68 69 73 20 73 75 70 65 72 63 6c 61 73 73   This superclass
36e60 20 65 78 69 73 74 73 20 69 6e 20 6f 72 64 65 72   exists in order
36e70 20 74 6f 20 64 65 66 69 6e 65 20 66 69 65 6c 64   to define field
36e80 73 20 6f 66 20 74 68 65 20 63 75 72 73 6f 72 20  s of the cursor 
36e90 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 6f 6d 6d  that.** are comm
36ea0 6f 6e 20 74 6f 20 61 6c 6c 20 69 6d 70 6c 65 6d  on to all implem
36eb0 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2f 0a 73 74  entations..*/.st
36ec0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
36ed0 62 5f 63 75 72 73 6f 72 20 7b 0a 20 20 73 71 6c  b_cursor {.  sql
36ee0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61 62  ite3_vtab *pVtab
36ef0 3b 20 20 20 20 20 20 2f 2a 20 56 69 72 74 75 61  ;      /* Virtua
36f00 6c 20 74 61 62 6c 65 20 6f 66 20 74 68 69 73 20  l table of this 
36f10 63 75 72 73 6f 72 20 2a 2f 0a 20 20 2f 2a 20 56  cursor */.  /* V
36f20 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70  irtual table imp
36f30 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c  lementations wil
36f40 6c 20 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20  l typically add 
36f50 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
36f60 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43  s */.};../*.** C
36f70 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65  API3REF: Declare
36f80 20 54 68 65 20 53 63 68 65 6d 61 20 4f 66 20 41   The Schema Of A
36f90 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a   Virtual Table.*
36fa0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 78 43 72 65 61  *.** ^The [xCrea
36fb0 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63  te] and [xConnec
36fc0 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 61 0a  t] methods of a.
36fd0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
36fe0 65 20 6d 6f 64 75 6c 65 5d 20 63 61 6c 6c 20 74  e module] call t
36ff0 68 69 73 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  his interface.**
37000 20 74 6f 20 64 65 63 6c 61 72 65 20 74 68 65 20   to declare the 
37010 66 6f 72 6d 61 74 20 28 74 68 65 20 6e 61 6d 65  format (the name
37020 73 20 61 6e 64 20 64 61 74 61 74 79 70 65 73 20  s and datatypes 
37030 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 29 20  of the columns) 
37040 6f 66 0a 2a 2a 20 74 68 65 20 76 69 72 74 75 61  of.** the virtua
37050 6c 20 74 61 62 6c 65 73 20 74 68 65 79 20 69 6d  l tables they im
37060 70 6c 65 6d 65 6e 74 2e 0a 2a 2f 0a 53 51 4c 49  plement..*/.SQLI
37070 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
37080 65 33 5f 64 65 63 6c 61 72 65 5f 76 74 61 62 28  e3_declare_vtab(
37090 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73 74 20  sqlite3*, const 
370a0 63 68 61 72 20 2a 7a 53 51 4c 29 3b 0a 0a 2f 2a  char *zSQL);../*
370b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 76  .** CAPI3REF: Ov
370c0 65 72 6c 6f 61 64 20 41 20 46 75 6e 63 74 69 6f  erload A Functio
370d0 6e 20 46 6f 72 20 41 20 56 69 72 74 75 61 6c 20  n For A Virtual 
370e0 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 28 56 69  Table.**.** ^(Vi
370f0 72 74 75 61 6c 20 74 61 62 6c 65 73 20 63 61 6e  rtual tables can
37100 20 70 72 6f 76 69 64 65 20 61 6c 74 65 72 6e 61   provide alterna
37110 74 69 76 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tive implementat
37120 69 6f 6e 73 20 6f 66 20 66 75 6e 63 74 69 6f 6e  ions of function
37130 73 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 20 5b  s.** using the [
37140 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 5d 20 6d  xFindFunction] m
37150 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 76 69  ethod of the [vi
37160 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
37170 6c 65 5d 2e 20 20 0a 2a 2a 20 42 75 74 20 67 6c  le].  .** But gl
37180 6f 62 61 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66  obal versions of
37190 20 74 68 6f 73 65 20 66 75 6e 63 74 69 6f 6e 73   those functions
371a0 0a 2a 2a 20 6d 75 73 74 20 65 78 69 73 74 20 69  .** must exist i
371b0 6e 20 6f 72 64 65 72 20 74 6f 20 62 65 20 6f 76  n order to be ov
371c0 65 72 6c 6f 61 64 65 64 2e 29 5e 0a 2a 2a 0a 2a  erloaded.)^.**.*
371d0 2a 20 5e 28 54 68 69 73 20 41 50 49 20 6d 61 6b  * ^(This API mak
371e0 65 73 20 73 75 72 65 20 61 20 67 6c 6f 62 61 6c  es sure a global
371f0 20 76 65 72 73 69 6f 6e 20 6f 66 20 61 20 66 75   version of a fu
37200 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 70 61  nction with a pa
37210 72 74 69 63 75 6c 61 72 0a 2a 2a 20 6e 61 6d 65  rticular.** name
37220 20 61 6e 64 20 6e 75 6d 62 65 72 20 6f 66 20 70   and number of p
37230 61 72 61 6d 65 74 65 72 73 20 65 78 69 73 74 73  arameters exists
37240 2e 20 20 49 66 20 6e 6f 20 73 75 63 68 20 66 75  .  If no such fu
37250 6e 63 74 69 6f 6e 20 65 78 69 73 74 73 0a 2a 2a  nction exists.**
37260 20 62 65 66 6f 72 65 20 74 68 69 73 20 41 50 49   before this API
37270 20 69 73 20 63 61 6c 6c 65 64 2c 20 61 20 6e 65   is called, a ne
37280 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 72  w function is cr
37290 65 61 74 65 64 2e 29 5e 20 20 5e 54 68 65 20 69  eated.)^  ^The i
372a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a  mplementation.**
372b0 20 6f 66 20 74 68 65 20 6e 65 77 20 66 75 6e 63   of the new func
372c0 74 69 6f 6e 20 61 6c 77 61 79 73 20 63 61 75 73  tion always caus
372d0 65 73 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 20  es an exception 
372e0 74 6f 20 62 65 20 74 68 72 6f 77 6e 2e 20 20 53  to be thrown.  S
372f0 6f 0a 2a 2a 20 74 68 65 20 6e 65 77 20 66 75 6e  o.** the new fun
37300 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 67 6f 6f  ction is not goo
37310 64 20 66 6f 72 20 61 6e 79 74 68 69 6e 67 20 62  d for anything b
37320 79 20 69 74 73 65 6c 66 2e 20 20 49 74 73 20 6f  y itself.  Its o
37330 6e 6c 79 0a 2a 2a 20 70 75 72 70 6f 73 65 20 69  nly.** purpose i
37340 73 20 74 6f 20 62 65 20 61 20 70 6c 61 63 65 68  s to be a placeh
37350 6f 6c 64 65 72 20 66 75 6e 63 74 69 6f 6e 20 74  older function t
37360 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 6c  hat can be overl
37370 6f 61 64 65 64 0a 2a 2a 20 62 79 20 61 20 5b 76  oaded.** by a [v
37380 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 2e 0a 2a  irtual table]..*
37390 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
373a0 20 73 71 6c 69 74 65 33 5f 6f 76 65 72 6c 6f 61   sqlite3_overloa
373b0 64 5f 66 75 6e 63 74 69 6f 6e 28 73 71 6c 69 74  d_function(sqlit
373c0 65 33 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  e3*, const char 
373d0 2a 7a 46 75 6e 63 4e 61 6d 65 2c 20 69 6e 74 20  *zFuncName, int 
373e0 6e 41 72 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  nArg);../*.** Th
373f0 65 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74  e interface to t
37400 68 65 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65  he virtual-table
37410 20 6d 65 63 68 61 6e 69 73 6d 20 64 65 66 69 6e   mechanism defin
37420 65 64 20 61 62 6f 76 65 20 28 62 61 63 6b 20 75  ed above (back u
37430 70 0a 2a 2a 20 74 6f 20 61 20 63 6f 6d 6d 65 6e  p.** to a commen
37440 74 20 72 65 6d 61 72 6b 61 62 6c 79 20 73 69 6d  t remarkably sim
37450 69 6c 61 72 20 74 6f 20 74 68 69 73 20 6f 6e 65  ilar to this one
37460 29 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 63  ) is currently c
37470 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20  onsidered.** to 
37480 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  be experimental.
37490 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
374a0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 20  might change in 
374b0 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61 79  incompatible way
374c0 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69 73  s..** If this is
374d0 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79   a problem for y
374e0 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20 74  ou, do not use t
374f0 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74 20  he interface at 
37500 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  this time..**.**
37510 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75 61   When the virtua
37520 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
37530 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77 65  m stabilizes, we
37540 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74 68   will declare th
37550 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 66  e.** interface f
37560 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69 74  ixed, support it
37570 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20 61   indefinitely, a
37580 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20 63  nd remove this c
37590 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a  omment..*/../*.*
375a0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 20 48 61  * CAPI3REF: A Ha
375b0 6e 64 6c 65 20 54 6f 20 41 6e 20 4f 70 65 6e 20  ndle To An Open 
375c0 42 4c 4f 42 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  BLOB.** KEYWORDS
375d0 3a 20 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 7d 20  : {BLOB handle} 
375e0 7b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 7d 0a 2a  {BLOB handles}.*
375f0 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
37600 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
37610 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
37620 65 6e 20 42 4c 4f 42 20 6f 6e 20 77 68 69 63 68  en BLOB on which
37630 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
37640 62 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65  b_open | increme
37650 6e 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 63  ntal BLOB I/O] c
37660 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 2e  an be performed.
37670 0a 2a 2a 20 5e 4f 62 6a 65 63 74 73 20 6f 66 20  .** ^Objects of 
37680 74 68 69 73 20 74 79 70 65 20 61 72 65 20 63 72  this type are cr
37690 65 61 74 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eated by [sqlite
376a0 33 5f 62 6c 6f 62 5f 6f 70 65 6e 28 29 5d 0a 2a  3_blob_open()].*
376b0 2a 20 61 6e 64 20 64 65 73 74 72 6f 79 65 64 20  * and destroyed 
376c0 62 79 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  by [sqlite3_blob
376d0 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 20 5e 54  _close()]..** ^T
376e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  he [sqlite3_blob
376f0 5f 72 65 61 64 28 29 5d 20 61 6e 64 20 5b 73 71  _read()] and [sq
37700 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72 69 74 65  lite3_blob_write
37710 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  ()] interfaces.*
37720 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  * can be used to
37730 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 73   read or write s
37740 6d 61 6c 6c 20 73 75 62 73 65 63 74 69 6f 6e 73  mall subsections
37750 20 6f 66 20 74 68 65 20 42 4c 4f 42 2e 0a 2a 2a   of the BLOB..**
37760 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 62   ^The [sqlite3_b
37770 6c 6f 62 5f 62 79 74 65 73 28 29 5d 20 69 6e 74  lob_bytes()] int
37780 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
37790 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 42  he size of the B
377a0 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 0a 2a 2f  LOB in bytes..*/
377b0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
377c0 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 73 71 6c  sqlite3_blob sql
377d0 69 74 65 33 5f 62 6c 6f 62 3b 0a 0a 2f 2a 0a 2a  ite3_blob;../*.*
377e0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e  * CAPI3REF: Open
377f0 20 41 20 42 4c 4f 42 20 46 6f 72 20 49 6e 63 72   A BLOB For Incr
37800 65 6d 65 6e 74 61 6c 20 49 2f 4f 0a 2a 2a 0a 2a  emental I/O.**.*
37810 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61  * ^(This interfa
37820 63 65 73 20 6f 70 65 6e 73 20 61 20 5b 42 4c 4f  ces opens a [BLO
37830 42 20 68 61 6e 64 6c 65 20 7c 20 68 61 6e 64 6c  B handle | handl
37840 65 5d 20 74 6f 20 74 68 65 20 42 4c 4f 42 20 6c  e] to the BLOB l
37850 6f 63 61 74 65 64 0a 2a 2a 20 69 6e 20 72 6f 77  ocated.** in row
37860 20 69 52 6f 77 2c 20 63 6f 6c 75 6d 6e 20 7a 43   iRow, column zC
37870 6f 6c 75 6d 6e 2c 20 74 61 62 6c 65 20 7a 54 61  olumn, table zTa
37880 62 6c 65 20 69 6e 20 64 61 74 61 62 61 73 65 20  ble in database 
37890 7a 44 62 3b 0a 2a 2a 20 69 6e 20 6f 74 68 65 72  zDb;.** in other
378a0 20 77 6f 72 64 73 2c 20 74 68 65 20 73 61 6d 65   words, the same
378b0 20 42 4c 4f 42 20 74 68 61 74 20 77 6f 75 6c 64   BLOB that would
378c0 20 62 65 20 73 65 6c 65 63 74 65 64 20 62 79 3a   be selected by:
378d0 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e 0a 2a 2a 20  .**.** <pre>.** 
378e0 20 20 20 20 53 45 4c 45 43 54 20 7a 43 6f 6c 75      SELECT zColu
378f0 6d 6e 20 46 52 4f 4d 20 7a 44 62 2e 7a 54 61 62  mn FROM zDb.zTab
37900 6c 65 20 57 48 45 52 45 20 5b 72 6f 77 69 64 5d  le WHERE [rowid]
37910 20 3d 20 69 52 6f 77 3b 0a 2a 2a 20 3c 2f 70 72   = iRow;.** </pr
37920 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  e>)^.**.** ^If t
37930 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  he flags paramet
37940 65 72 20 69 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  er is non-zero, 
37950 74 68 65 6e 20 74 68 65 20 42 4c 4f 42 20 69 73  then the BLOB is
37960 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
37970 0a 2a 2a 20 61 6e 64 20 77 72 69 74 65 20 61 63  .** and write ac
37980 63 65 73 73 2e 20 5e 49 66 20 69 74 20 69 73 20  cess. ^If it is 
37990 7a 65 72 6f 2c 20 74 68 65 20 42 4c 4f 42 20 69  zero, the BLOB i
379a0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
379b0 64 20 61 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 74  d access..** ^It
379c0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
379d0 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f 6c 75 6d   to open a colum
379e0 6e 20 74 68 61 74 20 69 73 20 70 61 72 74 20 6f  n that is part o
379f0 66 20 61 6e 20 69 6e 64 65 78 20 6f 72 20 70 72  f an index or pr
37a00 69 6d 61 72 79 20 0a 2a 2a 20 6b 65 79 20 66 6f  imary .** key fo
37a10 72 20 77 72 69 74 69 6e 67 2e 20 5e 49 66 20 5b  r writing. ^If [
37a20 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
37a30 74 72 61 69 6e 74 73 5d 20 61 72 65 20 65 6e 61  traints] are ena
37a40 62 6c 65 64 2c 20 69 74 20 69 73 20 0a 2a 2a 20  bled, it is .** 
37a50 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
37a60 6f 70 65 6e 20 61 20 63 6f 6c 75 6d 6e 20 74 68  open a column th
37a70 61 74 20 69 73 20 70 61 72 74 20 6f 66 20 61 20  at is part of a 
37a80 5b 63 68 69 6c 64 20 6b 65 79 5d 20 66 6f 72 20  [child key] for 
37a90 77 72 69 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e  writing..**.** ^
37aa0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 64 61  Note that the da
37ab0 74 61 62 61 73 65 20 6e 61 6d 65 20 69 73 20 6e  tabase name is n
37ac0 6f 74 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  ot the filename 
37ad0 74 68 61 74 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  that contains.**
37ae0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
37af0 74 20 72 61 74 68 65 72 20 74 68 65 20 73 79 6d  t rather the sym
37b00 62 6f 6c 69 63 20 6e 61 6d 65 20 6f 66 20 74 68  bolic name of th
37b10 65 20 64 61 74 61 62 61 73 65 20 74 68 61 74 0a  e database that.
37b20 2a 2a 20 61 70 70 65 61 72 73 20 61 66 74 65 72  ** appears after
37b30 20 74 68 65 20 41 53 20 6b 65 79 77 6f 72 64 20   the AS keyword 
37b40 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
37b50 65 20 69 73 20 63 6f 6e 6e 65 63 74 65 64 20 75  e is connected u
37b60 73 69 6e 67 20 5b 41 54 54 41 43 48 5d 2e 0a 2a  sing [ATTACH]..*
37b70 2a 20 5e 46 6f 72 20 74 68 65 20 6d 61 69 6e 20  * ^For the main 
37b80 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 74  database file, t
37b90 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
37ba0 20 69 73 20 22 6d 61 69 6e 22 2e 0a 2a 2a 20 5e   is "main"..** ^
37bb0 46 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 2c  For TEMP tables,
37bc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
37bd0 6d 65 20 69 73 20 22 74 65 6d 70 22 2e 0a 2a 2a  me is "temp"..**
37be0 0a 2a 2a 20 5e 28 4f 6e 20 73 75 63 63 65 73 73  .** ^(On success
37bf0 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73  , [SQLITE_OK] is
37c00 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 74 68   returned and th
37c10 65 20 6e 65 77 20 5b 42 4c 4f 42 20 68 61 6e 64  e new [BLOB hand
37c20 6c 65 5d 20 69 73 20 77 72 69 74 74 65 6e 0a 2a  le] is written.*
37c30 2a 20 74 6f 20 2a 70 70 42 6c 6f 62 2e 20 4f 74  * to *ppBlob. Ot
37c40 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
37c50 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
37c60 6e 65 64 20 61 6e 64 20 2a 70 70 42 6c 6f 62 20  ned and *ppBlob 
37c70 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 62 65 20  is set.** to be 
37c80 61 20 6e 75 6c 6c 20 70 6f 69 6e 74 65 72 2e 29  a null pointer.)
37c90 5e 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  ^.** ^This funct
37ca0 69 6f 6e 20 73 65 74 73 20 74 68 65 20 5b 64 61  ion sets the [da
37cb0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37cc0 6e 5d 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  n] error code an
37cd0 64 20 6d 65 73 73 61 67 65 0a 2a 2a 20 61 63 63  d message.** acc
37ce0 65 73 73 69 62 6c 65 20 76 69 61 20 5b 73 71 6c  essible via [sql
37cf0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
37d00 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  and [sqlite3_err
37d10 6d 73 67 28 29 5d 20 61 6e 64 20 72 65 6c 61 74  msg()] and relat
37d20 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 2e  ed.** functions.
37d30 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
37d40 2a 70 70 42 6c 6f 62 20 76 61 72 69 61 62 6c 65  *ppBlob variable
37d50 20 69 73 20 61 6c 77 61 79 73 20 69 6e 69 74 69   is always initi
37d60 61 6c 69 7a 65 64 20 69 6e 20 61 0a 2a 2a 20 77  alized in a.** w
37d70 61 79 20 74 68 61 74 20 6d 61 6b 65 73 20 69 74  ay that makes it
37d80 20 73 61 66 65 20 74 6f 20 69 6e 76 6f 6b 65 20   safe to invoke 
37d90 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
37da0 6f 73 65 28 29 5d 20 6f 6e 20 2a 70 70 42 6c 6f  ose()] on *ppBlo
37db0 62 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  b.** regardless 
37dc0 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 20 6f  of the success o
37dd0 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 69  r failure of thi
37de0 73 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 0a 2a 2a  s routine..**.**
37df0 20 5e 28 49 66 20 74 68 65 20 72 6f 77 20 74 68   ^(If the row th
37e00 61 74 20 61 20 42 4c 4f 42 20 68 61 6e 64 6c 65  at a BLOB handle
37e10 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 6d 6f   points to is mo
37e20 64 69 66 69 65 64 20 62 79 20 61 6e 0a 2a 2a 20  dified by an.** 
37e30 5b 55 50 44 41 54 45 5d 2c 20 5b 44 45 4c 45 54  [UPDATE], [DELET
37e40 45 5d 2c 20 6f 72 20 62 79 20 5b 4f 4e 20 43 4f  E], or by [ON CO
37e50 4e 46 4c 49 43 54 5d 20 73 69 64 65 2d 65 66 66  NFLICT] side-eff
37e60 65 63 74 73 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ects.** then the
37e70 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73 20   BLOB handle is 
37e80 6d 61 72 6b 65 64 20 61 73 20 22 65 78 70 69 72  marked as "expir
37e90 65 64 22 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ed"..** This is 
37ea0 74 72 75 65 20 69 66 20 61 6e 79 20 63 6f 6c 75  true if any colu
37eb0 6d 6e 20 6f 66 20 74 68 65 20 72 6f 77 20 69 73  mn of the row is
37ec0 20 63 68 61 6e 67 65 64 2c 20 65 76 65 6e 20 61   changed, even a
37ed0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6f 74 68 65 72   column.** other
37ee0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 74 68   than the one th
37ef0 65 20 42 4c 4f 42 20 68 61 6e 64 6c 65 20 69 73  e BLOB handle is
37f00 20 6f 70 65 6e 20 6f 6e 2e 29 5e 0a 2a 2a 20 5e   open on.)^.** ^
37f10 43 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  Calls to [sqlite
37f20 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20 61  3_blob_read()] a
37f30 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  nd [sqlite3_blob
37f40 5f 77 72 69 74 65 28 29 5d 20 66 6f 72 0a 2a 2a  _write()] for.**
37f50 20 61 20 65 78 70 69 72 65 64 20 42 4c 4f 42 20   a expired BLOB 
37f60 68 61 6e 64 6c 65 20 66 61 69 6c 20 77 69 74 68  handle fail with
37f70 20 61 6e 20 72 65 74 75 72 6e 20 63 6f 64 65 20   an return code 
37f80 6f 66 20 5b 53 51 4c 49 54 45 5f 41 42 4f 52 54  of [SQLITE_ABORT
37f90 5d 2e 0a 2a 2a 20 5e 28 43 68 61 6e 67 65 73 20  ]..** ^(Changes 
37fa0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 61 20 42  written into a B
37fb0 4c 4f 42 20 70 72 69 6f 72 20 74 6f 20 74 68 65  LOB prior to the
37fc0 20 42 4c 4f 42 20 65 78 70 69 72 69 6e 67 20 61   BLOB expiring a
37fd0 72 65 20 6e 6f 74 0a 2a 2a 20 72 6f 6c 6c 65 64  re not.** rolled
37fe0 20 62 61 63 6b 20 62 79 20 74 68 65 20 65 78 70   back by the exp
37ff0 69 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 42  iration of the B
38000 4c 4f 42 2e 20 20 53 75 63 68 20 63 68 61 6e 67  LOB.  Such chang
38010 65 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  es will eventual
38020 6c 79 0a 2a 2a 20 63 6f 6d 6d 69 74 20 69 66 20  ly.** commit if 
38030 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
38040 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d  continues to com
38050 70 6c 65 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  pletion.)^.**.**
38060 20 5e 55 73 65 20 74 68 65 20 5b 73 71 6c 69 74   ^Use the [sqlit
38070 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28 29 5d  e3_blob_bytes()]
38080 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 64 65   interface to de
38090 74 65 72 6d 69 6e 65 20 74 68 65 20 73 69 7a 65  termine the size
380a0 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 65   of.** the opene
380b0 64 20 62 6c 6f 62 2e 20 20 5e 54 68 65 20 73 69  d blob.  ^The si
380c0 7a 65 20 6f 66 20 61 20 62 6c 6f 62 20 6d 61 79  ze of a blob may
380d0 20 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20   not be changed 
380e0 62 79 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72  by this.** inter
380f0 66 61 63 65 2e 20 20 55 73 65 20 74 68 65 20 5b  face.  Use the [
38100 55 50 44 41 54 45 5d 20 53 51 4c 20 63 6f 6d 6d  UPDATE] SQL comm
38110 61 6e 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  and to change th
38120 65 20 73 69 7a 65 20 6f 66 20 61 0a 2a 2a 20 62  e size of a.** b
38130 6c 6f 62 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lob..**.** ^The 
38140 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65  [sqlite3_bind_ze
38150 72 6f 62 6c 6f 62 28 29 5d 20 61 6e 64 20 5b 73  roblob()] and [s
38160 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
38170 72 6f 62 6c 6f 62 28 29 5d 20 69 6e 74 65 72 66  roblob()] interf
38180 61 63 65 73 0a 2a 2a 20 61 6e 64 20 74 68 65 20  aces.** and the 
38190 62 75 69 6c 74 2d 69 6e 20 5b 7a 65 72 6f 62 6c  built-in [zerobl
381a0 6f 62 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ob] SQL function
381b0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 69 66   can be used, if
381c0 20 64 65 73 69 72 65 64 2c 0a 2a 2a 20 74 6f 20   desired,.** to 
381d0 63 72 65 61 74 65 20 61 6e 20 65 6d 70 74 79 2c  create an empty,
381e0 20 7a 65 72 6f 2d 66 69 6c 6c 65 64 20 62 6c 6f   zero-filled blo
381f0 62 20 69 6e 20 77 68 69 63 68 20 74 6f 20 72 65  b in which to re
38200 61 64 20 6f 72 20 77 72 69 74 65 20 75 73 69 6e  ad or write usin
38210 67 0a 2a 2a 20 74 68 69 73 20 69 6e 74 65 72 66  g.** this interf
38220 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 6f 20 61 76  ace..**.** To av
38230 6f 69 64 20 61 20 72 65 73 6f 75 72 63 65 20 6c  oid a resource l
38240 65 61 6b 2c 20 65 76 65 72 79 20 6f 70 65 6e 20  eak, every open 
38250 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 5d 20 73 68  [BLOB handle] sh
38260 6f 75 6c 64 20 65 76 65 6e 74 75 61 6c 6c 79 0a  ould eventually.
38270 2a 2a 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ** be released b
38280 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  y a call to [sql
38290 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28  ite3_blob_close(
382a0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
382b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 6c  I int sqlite3_bl
382c0 6f 62 5f 6f 70 65 6e 28 0a 20 20 73 71 6c 69 74  ob_open(.  sqlit
382d0 65 33 2a 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  e3*,.  const cha
382e0 72 20 2a 7a 44 62 2c 0a 20 20 63 6f 6e 73 74 20  r *zDb,.  const 
382f0 63 68 61 72 20 2a 7a 54 61 62 6c 65 2c 0a 20 20  char *zTable,.  
38300 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c  const char *zCol
38310 75 6d 6e 2c 0a 20 20 73 71 6c 69 74 65 33 5f 69  umn,.  sqlite3_i
38320 6e 74 36 34 20 69 52 6f 77 2c 0a 20 20 69 6e 74  nt64 iRow,.  int
38330 20 66 6c 61 67 73 2c 0a 20 20 73 71 6c 69 74 65   flags,.  sqlite
38340 33 5f 62 6c 6f 62 20 2a 2a 70 70 42 6c 6f 62 0a  3_blob **ppBlob.
38350 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38360 45 46 3a 20 4d 6f 76 65 20 61 20 42 4c 4f 42 20  EF: Move a BLOB 
38370 48 61 6e 64 6c 65 20 74 6f 20 61 20 4e 65 77 20  Handle to a New 
38380 52 6f 77 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  Row.**.** ^This 
38390 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
383a0 20 74 6f 20 6d 6f 76 65 20 61 6e 20 65 78 69 73   to move an exis
383b0 74 69 6e 67 20 62 6c 6f 62 20 68 61 6e 64 6c 65  ting blob handle
383c0 20 73 6f 20 74 68 61 74 20 69 74 20 70 6f 69 6e   so that it poin
383d0 74 73 0a 2a 2a 20 74 6f 20 61 20 64 69 66 66 65  ts.** to a diffe
383e0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
383f0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 74 61  same database ta
38400 62 6c 65 2e 20 5e 54 68 65 20 6e 65 77 20 72 6f  ble. ^The new ro
38410 77 20 69 73 20 69 64 65 6e 74 69 66 69 65 64 0a  w is identified.
38420 2a 2a 20 62 79 20 74 68 65 20 72 6f 77 69 64 20  ** by the rowid 
38430 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
38440 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
38450 65 6e 74 2e 20 4f 6e 6c 79 20 74 68 65 20 72 6f  ent. Only the ro
38460 77 20 63 61 6e 20 62 65 0a 2a 2a 20 63 68 61 6e  w can be.** chan
38470 67 65 64 2e 20 5e 54 68 65 20 64 61 74 61 62 61  ged. ^The databa
38480 73 65 2c 20 74 61 62 6c 65 20 61 6e 64 20 63 6f  se, table and co
38490 6c 75 6d 6e 20 6f 6e 20 77 68 69 63 68 20 74 68  lumn on which th
384a0 65 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 69 73  e blob handle is
384b0 20 6f 70 65 6e 0a 2a 2a 20 72 65 6d 61 69 6e 20   open.** remain 
384c0 74 68 65 20 73 61 6d 65 2e 20 4d 6f 76 69 6e 67  the same. Moving
384d0 20 61 6e 20 65 78 69 73 74 69 6e 67 20 62 6c 6f   an existing blo
384e0 62 20 68 61 6e 64 6c 65 20 74 6f 20 61 20 6e 65  b handle to a ne
384f0 77 20 72 6f 77 20 63 61 6e 20 62 65 0a 2a 2a 20  w row can be.** 
38500 66 61 73 74 65 72 20 74 68 61 6e 20 63 6c 6f 73  faster than clos
38510 69 6e 67 20 74 68 65 20 65 78 69 73 74 69 6e 67  ing the existing
38520 20 68 61 6e 64 6c 65 20 61 6e 64 20 6f 70 65 6e   handle and open
38530 69 6e 67 20 61 20 6e 65 77 20 6f 6e 65 2e 0a 2a  ing a new one..*
38540 2a 0a 2a 2a 20 5e 28 54 68 65 20 6e 65 77 20 72  *.** ^(The new r
38550 6f 77 20 6d 75 73 74 20 6d 65 65 74 20 74 68 65  ow must meet the
38560 20 73 61 6d 65 20 63 72 69 74 65 72 69 61 20 61   same criteria a
38570 73 20 66 6f 72 20 5b 73 71 6c 69 74 65 33 5f 62  s for [sqlite3_b
38580 6c 6f 62 5f 6f 70 65 6e 28 29 5d 20 2d 0a 2a 2a  lob_open()] -.**
38590 20 69 74 20 6d 75 73 74 20 65 78 69 73 74 20 61   it must exist a
385a0 6e 64 20 74 68 65 72 65 20 6d 75 73 74 20 62 65  nd there must be
385b0 20 65 69 74 68 65 72 20 61 20 62 6c 6f 62 20 6f   either a blob o
385c0 72 20 74 65 78 74 20 76 61 6c 75 65 20 73 74 6f  r text value sto
385d0 72 65 64 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 6f  red in.** the no
385e0 6d 69 6e 61 74 65 64 20 63 6f 6c 75 6d 6e 2e 29  minated column.)
385f0 5e 20 5e 49 66 20 74 68 65 20 6e 65 77 20 72 6f  ^ ^If the new ro
38600 77 20 69 73 20 6e 6f 74 20 70 72 65 73 65 6e 74  w is not present
38610 20 69 6e 20 74 68 65 20 74 61 62 6c 65 2c 20 6f   in the table, o
38620 72 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20  r if.** it does 
38630 6e 6f 74 20 63 6f 6e 74 61 69 6e 20 61 20 62 6c  not contain a bl
38640 6f 62 20 6f 72 20 74 65 78 74 20 76 61 6c 75 65  ob or text value
38650 2c 20 6f 72 20 69 66 20 61 6e 6f 74 68 65 72 20  , or if another 
38660 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 61 6e  error occurs, an
38670 0a 2a 2a 20 53 51 4c 69 74 65 20 65 72 72 6f 72  .** SQLite error
38680 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
38690 64 20 61 6e 64 20 74 68 65 20 62 6c 6f 62 20 68  d and the blob h
386a0 61 6e 64 6c 65 20 69 73 20 63 6f 6e 73 69 64 65  andle is conside
386b0 72 65 64 20 61 62 6f 72 74 65 64 2e 0a 2a 2a 20  red aborted..** 
386c0 5e 41 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20  ^All subsequent 
386d0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
386e0 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 2c 20  3_blob_read()], 
386f0 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 77 72  [sqlite3_blob_wr
38700 69 74 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ite()] or.** [sq
38710 6c 69 74 65 33 5f 62 6c 6f 62 5f 72 65 6f 70 65  lite3_blob_reope
38720 6e 28 29 5d 20 6f 6e 20 61 6e 20 61 62 6f 72 74  n()] on an abort
38730 65 64 20 62 6c 6f 62 20 68 61 6e 64 6c 65 20 69  ed blob handle i
38740 6d 6d 65 64 69 61 74 65 6c 79 20 72 65 74 75 72  mmediately retur
38750 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 41 42 4f 52  n.** SQLITE_ABOR
38760 54 2e 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  T. ^Calling [sql
38770 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73 28  ite3_blob_bytes(
38780 29 5d 20 6f 6e 20 61 6e 20 61 62 6f 72 74 65 64  )] on an aborted
38790 20 62 6c 6f 62 20 68 61 6e 64 6c 65 0a 2a 2a 20   blob handle.** 
387a0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a  always returns z
387b0 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ero..**.** ^This
387c0 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20 74   function sets t
387d0 68 65 20 64 61 74 61 62 61 73 65 20 68