System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact f85efae129144a471914185b89a8ed2910b7b76c:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 23 69 66 6e 64 65 66 20 53 51  ndif..#ifndef SQ
0710: 4c 49 54 45 5f 41 50 49 0a 23 20 64 65 66 69 6e  LITE_API.# defin
0720: 65 20 53 51 4c 49 54 45 5f 41 50 49 0a 23 65 6e  e SQLITE_API.#en
0730: 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  dif.../*.** Thes
0740: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0750: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0760: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0770: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0780: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0790: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
07a0: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
07b0: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
07c0: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07d0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07e0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07f0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
0800: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
0810: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
0820: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0830: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0840: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0850: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0860: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0870: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0880: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0890: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
08a0: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
08b0: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
08c0: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08d0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08e0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08f0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
0900: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
0910: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
0920: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0930: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0940: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0950: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0960: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0970: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0980: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0990: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
09a0: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
09b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
09c0: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09e0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09f0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
0a00: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
0a10: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
0a20: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a30: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a40: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a50: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a60: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a70: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a80: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a90: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0aa0: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0ab0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0ac0: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0ad0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ae0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0af0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0b00: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0b10: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0b20: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b30: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b40: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b50: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b60: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b70: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b80: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b90: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0ba0: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0bb0: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0bc0: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0bd0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0be0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bf0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0c00: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0c10: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0c20: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c30: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c40: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c50: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c60: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c70: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c80: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c90: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0ca0: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0cb0: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0cc0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0cd0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0ce0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cf0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0d00: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0d10: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0d20: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d30: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d40: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d50: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d60: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d70: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d80: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d90: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0da0: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0db0: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0dc0: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0dd0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0de0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0df0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0e00: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0e10: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0e20: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e30: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e40: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e50: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e60: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e70: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e80: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e90: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0ea0: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0eb0: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0ec0: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ed0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0ee0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ef0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0f00: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0f10: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0f20: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f30: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f40: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f50: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f60: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f70: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f80: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f90: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0fa0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0fb0: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0fc0: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fd0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fe0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0ff0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
1000: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
1010: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 33  ERSION        "3
1020: 2e 37 2e 36 2e 33 22 0a 23 64 65 66 69 6e 65 20  .7.6.3".#define 
1030: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
1040: 55 4d 42 45 52 20 33 30 30 37 30 30 36 0a 23 64  UMBER 3007006.#d
1050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55  efine SQLITE_SOU
1060: 52 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31  RCE_ID      "201
1070: 31 2d 30 35 2d 31 39 20 31 33 3a 32 36 3a 35 34  1-05-19 13:26:54
1080: 20 65 64 31 64 61 35 31 30 61 32 33 39 65 61 37   ed1da510a239ea7
1090: 36 37 61 30 31 64 63 33 33 32 62 36 36 37 31 31  67a01dc332b66711
10a0: 39 66 61 33 63 39 30 38 65 22 0a 0a 2f 2a 0a 2a  9fa3c908e"../*.*
10b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
10c0: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72  Time Library Ver
10d0: 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20  sion Numbers.** 
10e0: 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
10f0: 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74  3_version, sqlit
1100: 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a  e3_sourceid.**.*
1110: 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63  * These interfac
1120: 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73  es provide the s
1130: 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ame information 
1140: 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56  as the [SQLITE_V
1150: 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c  ERSION],.** [SQL
1160: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1170: 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  ER], and [SQLITE
1180: 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72  _SOURCE_ID] C pr
1190: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
11a0: 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73  s.** but are ass
11b0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65  ociated with the
11c0: 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64   library instead
11d0: 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66   of the header f
11e0: 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73  ile.  ^(Cautious
11f0: 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20  .** programmers 
1200: 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73  might include as
1210: 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74  sert() statement
1220: 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69  s in their appli
1230: 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72  cation to.** ver
1240: 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20  ify that values 
1250: 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1260: 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74  e interfaces mat
1270: 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e  ch the macros in
1280: 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20  .** the header, 
1290: 61 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20  and thus insure 
12a0: 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61  that the applica
12b0: 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  tion is.** compi
12c0: 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e  led with matchin
12d0: 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65  g library and he
12e0: 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a  ader files..**.*
12f0: 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1300: 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73  re>.** assert( s
1310: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1320: 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49  n_number()==SQLI
1330: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1340: 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20  R );.** assert( 
1350: 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73  strcmp(sqlite3_s
1360: 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45  ourceid(),SQLITE
1370: 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29  _SOURCE_ID)==0 )
1380: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1390: 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76  cmp(sqlite3_libv
13a0: 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f  ersion(),SQLITE_
13b0: 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a  VERSION)==0 );.*
13c0: 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
13d0: 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
13e0: 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69  he sqlite3_versi
13f0: 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73  on[] string cons
1400: 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68  tant contains th
1410: 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54  e text of [SQLIT
1420: 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61  E_VERSION].** ma
1430: 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  cro.  ^The sqlit
1440: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20  e3_libversion() 
1450: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1460: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1470: 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69  e.** to the sqli
1480: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74  te3_version[] st
1490: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20  ring constant.  
14a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  The sqlite3_libv
14b0: 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63  ersion().** func
14c0: 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64  tion is provided
14d0: 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73   for use in DLLs
14e0: 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73   since DLL users
14f0: 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20   usually do not 
1500: 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61  have.** direct a
1510: 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20  ccess to string 
1520: 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e  constants within
1530: 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a   the DLL.  ^The.
1540: 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  ** sqlite3_libve
1550: 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66  rsion_number() f
1560: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1570: 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c  an integer equal
1580: 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56   to.** [SQLITE_V
1590: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20  ERSION_NUMBER]. 
15a0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f   ^The sqlite3_so
15b0: 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f  urceid() functio
15c0: 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20  n returns .** a 
15d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72  pointer to a str
15e0: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f  ing constant who
15f0: 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20  se value is the 
1600: 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20  same as the .** 
1610: 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49  [SQLITE_SOURCE_I
1620: 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  D] C preprocesso
1630: 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  r macro..**.** S
1640: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
1650: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20  _version()] and 
1660: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69  [sqlite_source_i
1670: 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  d()]..*/.SQLITE_
1680: 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52  API SQLITE_EXTER
1690: 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c  N const char sql
16a0: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a  ite3_version[];.
16b0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
16c0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c   char *sqlite3_l
16d0: 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b  ibversion(void);
16e0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
16f0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1700: 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a  sourceid(void);.
1710: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1720: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
1730: 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a  n_number(void);.
1740: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1750: 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72   Run-Time Librar
1760: 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70  y Compilation Op
1770: 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63  tions Diagnostic
1780: 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1790: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
17a0: 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69  on_used() functi
17b0: 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20  on returns 0 or 
17c0: 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  1 .** indicating
17d0: 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65   whether the spe
17e0: 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61  cified option wa
17f0: 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a  s defined at .**
1800: 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20   compile time.  
1810: 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65  ^The SQLITE_ pre
1820: 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  fix may be omitt
1830: 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20  ed from the .** 
1840: 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73  option name pass
1850: 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ed to sqlite3_co
1860: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1870: 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().  .**.** ^The
1880: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1890: 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e  option_get() fun
18a0: 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65  ction allows ite
18b0: 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74  rating.** over t
18c0: 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f  he list of optio
18d0: 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66  ns that were def
18e0: 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20  ined at compile 
18f0: 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72  time by.** retur
1900: 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f  ning the N-th co
1910: 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f  mpile time optio
1920: 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e  n string.  ^If N
1930: 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
1940: 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ,.** sqlite3_com
1950: 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29  pileoption_get()
1960: 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1970: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53  pointer.  ^The S
1980: 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69  QLITE_ .** prefi
1990: 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  x is omitted fro
19a0: 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65  m any strings re
19b0: 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71  turned by .** sq
19c0: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
19d0: 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a  ion_get()..**.**
19e0: 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68   ^Support for th
19f0: 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e  e diagnostic fun
1a00: 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63  ctions sqlite3_c
1a10: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1a20: 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  d().** and sqlit
1a30: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1a40: 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d  _get() may be om
1a50: 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79  itted by specify
1a60: 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ing the .** [SQL
1a70: 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45  ITE_OMIT_COMPILE
1a80: 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70  OPTION_DIAGS] op
1a90: 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20  tion at compile 
1aa0: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  time..**.** See 
1ab0: 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69  also: SQL functi
1ac0: 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  ons [sqlite_comp
1ad0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1ae0: 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
1af0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1b00: 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63  et()] and the [c
1b10: 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70  ompile_options p
1b20: 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64  ragma]..*/.#ifnd
1b30: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43  ef SQLITE_OMIT_C
1b40: 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41  OMPILEOPTION_DIA
1b50: 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  GS.SQLITE_API in
1b60: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  t sqlite3_compil
1b70: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e  eoption_used(con
1b80: 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d  st char *zOptNam
1b90: 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  e);.SQLITE_API c
1ba0: 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
1bb0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
1bc0: 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e  _get(int N);.#en
1bd0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
1be0: 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65  REF: Test To See
1bf0: 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20   If The Library 
1c00: 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a  Is Threadsafe.**
1c10: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1c20: 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75  _threadsafe() fu
1c30: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a  nction returns z
1c40: 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ero if and only 
1c50: 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73  if.** SQLite was
1c60: 20 63 6f 6d 70 69 6c 65 64 20 6d 75 74 65 78 69   compiled mutexi
1c70: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1c80: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c90: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1ca0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1cb0: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1cc0: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1cd0: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1ce0: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1cf0: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1d00: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1d10: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1d20: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1d30: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1d40: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1d50: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1d60: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1d70: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1d80: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d90: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1da0: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1db0: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1dc0: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1dd0: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1de0: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1df0: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1e00: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1e10: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1e20: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1e30: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1e40: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1e50: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1e60: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1e70: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1e80: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e90: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1ea0: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1eb0: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1ec0: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1ed0: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1ee0: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1ef0: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1f00: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1f10: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1f20: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1f30: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1f40: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1f50: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1f60: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1f70: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1f80: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f90: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1fa0: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1fb0: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1fc0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1fd0: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1fe0: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1ff0: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
2000: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
2010: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
2020: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
2030: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
2040: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
2050: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
2060: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
2070: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
2080: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2090: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
20a0: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
20b0: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
20c0: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
20d0: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
20e0: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
20f0: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2100: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2110: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2120: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
2130: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
2140: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
2150: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
2160: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
2170: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
2180: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2190: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
21a0: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
21b0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
21c0: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
21d0: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
21e0: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
21f0: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2200: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2210: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2220: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
2230: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
2240: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
2250: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
2260: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
2270: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
2280: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2290: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
22a0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
22b0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
22c0: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
22d0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
22e0: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
22f0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2300: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2310: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2320: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2330: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
2340: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2350: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
2360: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
2370: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
2380: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
2390: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
23a0: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
23b0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
23c0: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
23d0: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
23e0: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
23f0: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2400: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2410: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2420: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2430: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2440: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
2450: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
2460: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
2470: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
2480: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
2490: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
24a0: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
24b0: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
24c0: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
24d0: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
24e0: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
24f0: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2500: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2510: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2520: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2530: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
2540: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
2550: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
2560: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
2570: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
2580: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
2590: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
25a0: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
25b0: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
25c0: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
25d0: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
25e0: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
25f0: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2600: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2610: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2620: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2630: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
2640: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
2650: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
2660: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2670: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2680: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
2690: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
26a0: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
26b0: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
26c0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
26d0: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
26e0: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
26f0: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2700: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2710: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2720: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2730: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2740: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2750: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
2760: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
2770: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
2780: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
2790: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
27a0: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
27b0: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
27c0: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
27d0: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
27e0: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
27f0: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2800: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2810: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2820: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2830: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
2840: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
2850: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
2860: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
2870: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
2880: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2890: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
28a0: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
28b0: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
28c0: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
28d0: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
28e0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
28f0: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2900: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2910: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2920: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2930: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
2940: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
2950: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
2960: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
2970: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
2980: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
2990: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
29a0: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
29b0: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
29c0: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
29d0: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
29e0: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
29f0: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2a00: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2a10: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2a20: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2a30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
2a40: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
2a50: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
2a60: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
2a70: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
2a80: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
2a90: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2aa0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2ab0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2ac0: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2ad0: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2ae0: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2af0: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2b00: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2b10: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2b20: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2b30: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2b40: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2b50: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2b60: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2b70: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2b80: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2b90: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2ba0: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2bb0: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2bc0: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2bd0: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2be0: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2bf0: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2c00: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2c10: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2c20: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2c30: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2c40: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2c50: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2c60: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2c70: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2c80: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2c90: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2ca0: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2cb0: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2cc0: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2cd0: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2ce0: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2cf0: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2d00: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2d10: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2d20: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2d30: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2d40: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2d50: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2d60: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2d70: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2d80: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2d90: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2da0: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2db0: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2dc0: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2dd0: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2de0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2df0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2e00: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2e10: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2e20: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2e30: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2e40: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2e50: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2e60: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2e70: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2e80: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2e90: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2ea0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2eb0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c  qlite3_close(sql
2ec0: 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ite3 *);../*.** 
2ed0: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
2ee0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
2ef0: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
2f00: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
2f10: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
2f20: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
2f30: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
2f40: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
2f50: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
2f60: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
2f70: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
2f80: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
2f90: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
2fa0: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
2fb0: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
2fc0: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a  on Interface.**.
2fd0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
2fe0: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
2ff0: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  is a convenience
3000: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
3010: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
3020: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
3030: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
3040: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
3050: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61  ze()],.** that a
3060: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
3070: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74  tion to run mult
3080: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20  iple statements 
3090: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75  of SQL.** withou
30a0: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20  t having to use 
30b0: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
30c0: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
30d0: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
30e0: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20  rface runs zero 
30f0: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e  or more UTF-8 en
3100: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f  coded,.** semico
3110: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c  lon-separate SQL
3120: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3130: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20  ed into its 2nd 
3140: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20  argument,.** in 
3150: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
3160: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
3170: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20  nection] passed 
3180: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a  in as its 1st.**
3190: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
31a0: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
31b0: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64  ction of the 3rd
31c0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
31e0: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
31f0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66   it is invoked f
3200: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72  or each result r
3210: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74  ow.** coming out
3220: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65   of the evaluate
3230: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
3240: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
3250: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 6f 20 73 71  ment to.** to sq
3260: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3270: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
3280: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
3290: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
32a0: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
32b0: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
32c0: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
32d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
32e0: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
32f0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
3300: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
3310: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
3320: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
3330: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
3340: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
3350: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
3360: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
3370: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
3380: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
3390: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
33a0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
33b0: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
33c0: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
33d0: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
33e0: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
33f0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3400: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3410: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
3420: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
3430: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
3440: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
3450: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3460: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
3470: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
3480: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3490: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
34a0: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
34b0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34c0: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
34d0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
34e0: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
34f0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
3500: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
3510: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
3520: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  f.** of sqlite3_
3530: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
3540: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3550: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3560: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3570: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3580: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3590: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
35a0: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
35b0: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
35c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
35d0: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
35e0: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
35f0: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
3600: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
3610: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
3620: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3630: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
3640: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3650: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3660: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3670: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3680: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3690: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
36a0: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
36b0: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
36c0: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
36d0: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
36e0: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
36f0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3700: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3710: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3720: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3730: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3740: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3750: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3760: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3770: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3780: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3790: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
37a0: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
37b0: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
37c0: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
37d0: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
37e0: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
37f0: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3800: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3810: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3820: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3830: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3840: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3850: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3860: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3870: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3880: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3890: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
38a0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
38b0: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
38c0: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
38d0: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
38e0: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
38f0: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3900: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3910: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3920: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3930: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3940: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3950: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3960: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3970: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3980: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3990: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
39a0: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
39b0: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
39c0: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
39d0: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
39e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
39f0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3a00: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3a10: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3a20: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3a30: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3a40: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3a50: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
3a60: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
3a70: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
3a90: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
3aa0: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
3ab0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
3ac0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3ad0: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
3ae0: 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 20 63  lose [database c
3af0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
3b00: 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  fied by.**      
3b10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3b20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3b30: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
3b40: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
3b50: 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  ing..** <li> The
3b60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3b70: 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  t not modify the
3b80: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
3b90: 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  ext passed into.
3ba0: 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20  **      the 2nd 
3bb0: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
3bc0: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
3bd0: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3be0: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
3bf0: 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ul>.*/.SQLITE_
3c00: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
3c10: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
3c20: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
3c30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c40: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
3c50: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
3c60: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
3c70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c80: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
3c90: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
3ca0: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
3cb0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
3cc0: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
3cd0: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
3ce0: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
3cf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3d10: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
3d20: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
3d30: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
3d40: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
3d50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3d60: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
3d70: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
3d80: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
3d90: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
3da0: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
3db0: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d  _OK {error code}
3dc0: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a   {error codes}.*
3dd0: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73  * KEYWORDS: {res
3de0: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c  ult code} {resul
3df0: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d  t codes}.**.** M
3e00: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
3e10: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
3e20: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
3e30: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
3e40: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e  shown.** here in
3e50: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61   order to indica
3e60: 74 65 73 20 73 75 63 63 65 73 73 20 6f 72 20 66  tes success or f
3e70: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
3e80: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
3e90: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
3ea0: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
3eb0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
3ec0: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
3ed0: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
3ee0: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
3ef0: 64 65 73 5d 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  des].*/.#define 
3f00: 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20  SQLITE_OK       
3f10: 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65      0   /* Succe
3f20: 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a  ssful result */.
3f30: 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d  /* beginning-of-
3f40: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23  error-codes */.#
3f50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52  define SQLITE_ER
3f60: 52 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f  ROR        1   /
3f70: 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d  * SQL error or m
3f80: 69 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20  issing database 
3f90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
3fa0: 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32  E_INTERNAL     2
3fb0: 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c     /* Internal l
3fc0: 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51  ogic error in SQ
3fd0: 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  Lite */.#define 
3fe0: 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20  SQLITE_PERM     
3ff0: 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73      3   /* Acces
4000: 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e  s permission den
4010: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4020: 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20  QLITE_ABORT     
4030: 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61     4   /* Callba
4040: 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65  ck routine reque
4050: 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f  sted an abort */
4060: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4070: 42 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20  BUSY         5  
4080: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
4090: 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20   file is locked 
40a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
40b0: 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36  E_LOCKED       6
40c0: 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e     /* A table in
40d0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
40e0: 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69   locked */.#defi
40f0: 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  ne SQLITE_NOMEM 
4100: 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20         7   /* A 
4110: 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20  malloc() failed 
4120: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4130: 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38  E_READONLY     8
4140: 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f     /* Attempt to
4150: 20 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c   write a readonl
4160: 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64  y database */.#d
4170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
4180: 45 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a  ERRUPT    9   /*
4190: 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69   Operation termi
41a0: 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  nated by sqlite3
41b0: 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23  _interrupt()*/.#
41c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
41d0: 45 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f  ERR       10   /
41e0: 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64  * Some kind of d
41f0: 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63  isk I/O error oc
4200: 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e  curred */.#defin
4210: 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54  e SQLITE_CORRUPT
4220: 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65       11   /* The
4230: 20 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69   database disk i
4240: 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65  mage is malforme
4250: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4260: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20  ITE_NOTFOUND    
4270: 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20  12   /* Unknown 
4280: 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65  opcode in sqlite
4290: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
42a0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
42b0: 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31  TE_FULL        1
42c0: 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e  3   /* Insertion
42d0: 20 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20   failed because 
42e0: 64 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c  database is full
42f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4300: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31  TE_CANTOPEN    1
4310: 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f  4   /* Unable to
4320: 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
4330: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4340: 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43  ne SQLITE_PROTOC
4350: 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61  OL    15   /* Da
4360: 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74  tabase lock prot
4370: 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64  ocol error */.#d
4380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50  efine SQLITE_EMP
4390: 54 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a  TY       16   /*
43a0: 20 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70   Database is emp
43b0: 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ty */.#define SQ
43c0: 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20  LITE_SCHEMA     
43d0: 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74   17   /* The dat
43e0: 61 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61  abase schema cha
43f0: 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nged */.#define 
4400: 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20  SQLITE_TOOBIG   
4410: 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e     18   /* Strin
4420: 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64  g or BLOB exceed
4430: 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a  s size limit */.
4440: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
4450: 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20  ONSTRAINT  19   
4460: 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20  /* Abort due to 
4470: 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
4480: 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  tion */.#define 
4490: 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20  SQLITE_MISMATCH 
44a0: 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20     20   /* Data 
44b0: 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f  type mismatch */
44c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
44d0: 4d 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20  MISUSE      21  
44e0: 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64   /* Library used
44f0: 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a   incorrectly */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4510: 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20  OLFS       22   
4520: 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75  /* Uses OS featu
4530: 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65  res not supporte
4540: 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65  d on host */.#de
4550: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48  fine SQLITE_AUTH
4560: 20 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20          23   /* 
4570: 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65  Authorization de
4580: 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nied */.#define 
4590: 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20  SQLITE_FORMAT   
45a0: 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c     24   /* Auxil
45b0: 69 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f  iary database fo
45c0: 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64  rmat error */.#d
45d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e  efine SQLITE_RAN
45e0: 47 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a  GE       25   /*
45f0: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74   2nd parameter t
4600: 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f  o sqlite3_bind o
4610: 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23  ut of range */.#
4620: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
4630: 54 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f  TADB      26   /
4640: 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68  * File opened th
4650: 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61  at is not a data
4660: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
4670: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
4680: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
4690: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
46a0: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
46b0: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
46c0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
46d0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
46e0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
46f0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
4700: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
4710: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
4720: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
4730: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4740: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4750: 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   {extended error
4760: 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64   code} {extended
4770: 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a   error codes}.**
4780: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65   KEYWORDS: {exte
4790: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
47a0: 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75  } {extended resu
47b0: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
47c0: 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63  In its default c
47d0: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51  onfiguration, SQ
47e0: 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65  Lite API routine
47f0: 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  s return one of 
4800: 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53  26 integer.** [S
4810: 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c  QLITE_OK | resul
4820: 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76  t codes].  Howev
4830: 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68  er, experience h
4840: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61  as shown that ma
4850: 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72  ny of.** these r
4860: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4870: 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e  too coarse-grain
4880: 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74  ed.  They do not
4890: 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d   provide as.** m
48a0: 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  uch information 
48b0: 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61  about problems a
48c0: 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  s programmers mi
48d0: 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e  ght like.  In an
48e0: 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64   effort to.** ad
48f0: 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65  dress this, newe
4900: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
4910: 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e  Lite (version 3.
4920: 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69  3.8 and later) i
4930: 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72  nclude.** suppor
4940: 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  t for additional
4950: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68   result codes th
4960: 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20  at provide more 
4970: 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61  detailed informa
4980: 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72  tion.** about er
4990: 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64  rors. The extend
49a0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
49b0: 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  are enabled or d
49c0: 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20  isabled.** on a 
49d0: 70 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e  per database con
49e0: 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73  nection basis us
49f0: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
4a00: 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
4a10: 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49  ult_codes()] API
4a20: 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20  ..**.** Some of 
4a30: 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78  the available ex
4a40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4a50: 64 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68  des are listed h
4a60: 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20  ere..** One may 
4a70: 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65  expect the numbe
4a80: 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65  r of extended re
4a90: 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20  sult codes will 
4aa0: 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65  be expand.** ove
4ab0: 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72  r time.  Softwar
4ac0: 65 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65  e that uses exte
4ad0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
4ae0: 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a  s should expect.
4af0: 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65  ** to see new re
4b00: 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75  sult codes in fu
4b10: 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
4b20: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
4b30: 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73  he SQLITE_OK res
4b40: 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65  ult code will ne
4b50: 76 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e  ver be extended.
4b60: 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73    It will always
4b70: 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a  .** be exactly z
4b80: 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ero..*/.#define 
4b90: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
4ba0: 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  D              (
4bb0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
4bc0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
4bd0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
4be0: 54 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53  T_READ        (S
4bf0: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32  QLITE_IOERR | (2
4c00: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
4c10: 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45  LITE_IOERR_WRITE
4c20: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4c30: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c  LITE_IOERR | (3<
4c40: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4c50: 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20  ITE_IOERR_FSYNC 
4c60: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4c70: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c  ITE_IOERR | (4<<
4c80: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4c90: 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59  TE_IOERR_DIR_FSY
4ca0: 4e 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49  NC         (SQLI
4cb0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38  TE_IOERR | (5<<8
4cc0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4cd0: 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45  E_IOERR_TRUNCATE
4ce0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4cf0: 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29  E_IOERR | (6<<8)
4d00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4d10: 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20  _IOERR_FSTAT    
4d20: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4d30: 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29  _IOERR | (7<<8))
4d40: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4d50: 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20  IOERR_UNLOCK    
4d60: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4d70: 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a  IOERR | (8<<8)).
4d80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4d90: 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20  OERR_RDLOCK     
4da0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4db0: 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23  OERR | (9<<8)).#
4dc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4dd0: 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ERR_DELETE      
4de0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4df0: 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23  ERR | (10<<8)).#
4e00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4e10: 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20  ERR_BLOCKED     
4e20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4e30: 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23  ERR | (11<<8)).#
4e40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4e50: 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ERR_NOMEM       
4e60: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4e70: 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23  ERR | (12<<8)).#
4e80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4e90: 45 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20  ERR_ACCESS      
4ea0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4eb0: 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23  ERR | (13<<8)).#
4ec0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ed0: 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45  ERR_CHECKRESERVE
4ee0: 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f  DLOCK (SQLITE_IO
4ef0: 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23  ERR | (14<<8)).#
4f00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4f10: 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20  ERR_LOCK        
4f20: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4f30: 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23  ERR | (15<<8)).#
4f40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4f50: 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  ERR_CLOSE       
4f60: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4f70: 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23  ERR | (16<<8)).#
4f80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4f90: 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20  ERR_DIR_CLOSE   
4fa0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4fb0: 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23  ERR | (17<<8)).#
4fc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4fd0: 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20  ERR_SHMOPEN     
4fe0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4ff0: 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23  ERR | (18<<8)).#
5000: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5010: 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20  ERR_SHMSIZE     
5020: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5030: 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23  ERR | (19<<8)).#
5040: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5050: 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20  ERR_SHMLOCK     
5060: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5070: 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23  ERR | (20<<8)).#
5080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5090: 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45  CKED_SHAREDCACHE
50a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f        (SQLITE_LO
50b0: 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a  CKED |  (1<<8)).
50c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
50d0: 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20  USY_RECOVERY    
50e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42         (SQLITE_B
50f0: 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29  USY   |  (1<<8))
5100: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5110: 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44  CANTOPEN_NOTEMPD
5120: 49 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  IR      (SQLITE_
5130: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38  CANTOPEN | (1<<8
5140: 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ))../*.** CAPI3R
5150: 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69  EF: Flags For Fi
5160: 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f  le Open Operatio
5170: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62  ns.**.** These b
5180: 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  it values are in
5190: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
51a0: 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72  n the.** 3rd par
51b0: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
51c0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
51d0: 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a  ] interface and.
51e0: 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61  ** in the 4th pa
51f0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 78  rameter to the x
5200: 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66 20 74  Open method of t
5210: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  he.** [sqlite3_v
5220: 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23  fs] object..*/.#
5230: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5240: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
5250: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20      0x00000001  
5260: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5270: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5280: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5290: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
52a0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20      0x00000002  
52b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
52c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
52d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
52e0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
52f0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20      0x00000004  
5300: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5310: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5320: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5330: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
5340: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20      0x00000008  
5350: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5360: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5370: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
5380: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20      0x00000010  
5390: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
53a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
53b0: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20  EN_AUTOPROXY    
53c0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20      0x00000020  
53d0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
53e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
53f0: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
5400: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20      0x00000100  
5410: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5430: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
5440: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20      0x00000200  
5450: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5460: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5470: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
5480: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20      0x00000400  
5490: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
54a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
54b0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
54c0: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20      0x00000800  
54d0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
54e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
54f0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
5500: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20      0x00001000  
5510: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5520: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5530: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
5540: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20      0x00002000  
5550: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5560: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5570: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
5580: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20  L   0x00004000  
5590: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
55a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
55b0: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
55c0: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20      0x00008000  
55d0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
55e0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
55f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5600: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
5610: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20      0x00010000  
5620: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5630: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5640: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5650: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  EN_SHAREDCACHE  
5660: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20      0x00020000  
5670: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5680: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5690: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
56a0: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
56b0: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20      0x00040000  
56c0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
56d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
56e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
56f0: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  EN_WAL          
5700: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20      0x00080000  
5710: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a  /* VFS only */..
5720: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20  /* Reserved:    
5730: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5740: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20       0x00F00000 
5750: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
5760: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
5770: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  cteristics.**.**
5780: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
5790: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
57a0: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
57b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
57c0: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
57d0: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
57e0: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
57f0: 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69   the these.** bi
5800: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
5810: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
5820: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
5830: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
5840: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
5850: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
5860: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
5870: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
5880: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
5890: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
58a0: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
58b0: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
58c0: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
58d0: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
58e0: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
58f0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
5900: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
5910: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
5920: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
5930: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
5940: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
5950: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
5960: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
5970: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
5980: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
5990: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
59a0: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
59b0: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
59c0: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
59d0: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
59e0: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
59f0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
5a00: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
5a10: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
5a20: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
5a30: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
5a40: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
5a50: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
5a60: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
5a70: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
5a80: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
5a90: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
5aa0: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
5ab0: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
5ac0: 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  )..*/.#define SQ
5ad0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5ae0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
5af0: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
5b00: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5b10: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
5b20: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5b30: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
5b40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
5b50: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
5b60: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
5b70: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5b80: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
5b90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5ba0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
5bb0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
5bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5bd0: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
5be0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5bf0: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
5c00: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
5c10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5c20: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
5c30: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5c40: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
5c50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5c60: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
5c70: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
5c80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5c90: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
5ca0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5cb0: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
5cc0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
5cd0: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
5ce0: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
5cf0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5d00: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
5d10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
5d20: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
5d30: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
5d40: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
5d50: 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a 2a 2a  x00000800../*.**
5d60: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
5d70: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
5d80: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
5d90: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
5da0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
5db0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
5dc0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
5dd0: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
5de0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
5df0: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
5e00: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
5e10: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
5e20: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
5e30: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
5e40: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
5e50: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
5e60: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
5e70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
5e80: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
5e90: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
5ea0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
5eb0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
5ec0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
5ed0: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
5ee0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
5ef0: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
5f00: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
5f10: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
5f20: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
5f30: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
5f40: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5f50: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
5f60: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
5f70: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
5f80: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
5f90: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
5fa0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
5fb0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
5fc0: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
5fd0: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
5fe0: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
5ff0: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
6000: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
6010: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
6020: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
6030: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
6040: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
6050: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6060: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
6070: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
6080: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
6090: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
60a0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
60b0: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
60c0: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
60d0: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
60e0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
60f0: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
6100: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6110: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
6120: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
6130: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
6140: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6150: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6160: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
6170: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
6180: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6190: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
61a0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
61b0: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
61c0: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
61d0: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
61e0: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
61f0: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
6200: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
6210: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
6220: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
6230: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
6240: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
6250: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6260: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6270: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
6280: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
6290: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
62a0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
62b0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
62c0: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
62d0: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
62e0: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
62f0: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
6300: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
6310: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
6320: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
6330: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
6340: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
6350: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
6360: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6370: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
6380: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
6390: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
63a0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
63b0: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
63c0: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
63d0: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
63e0: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
63f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6400: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
6410: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
6420: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6430: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
6440: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
6450: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6460: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
6470: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6480: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
6490: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
64a0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
64b0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
64c0: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
64d0: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
64e0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
64f0: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
6500: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
6510: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
6520: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
6530: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
6540: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
6550: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
6560: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
6570: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
6580: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
6590: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
65a0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
65b0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
65c0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
65d0: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
65e0: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
65f0: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
6600: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
6610: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
6620: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
6630: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
6640: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
6650: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
6660: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
6670: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
6680: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
6690: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
66a0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
66b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
66c0: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
66d0: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
66e0: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
66f0: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
6700: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6710: 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  s] xOpen method 
6720: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
6730: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6740: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
6750: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
6760: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
6770: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6780: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
6790: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
67a0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
67b0: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
67c0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
67d0: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
67e0: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
67f0: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
6800: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
6810: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
6820: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
6830: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
6840: 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65 6e 20  ** If the xOpen 
6850: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
6860: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
6870: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
6880: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
6890: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
68a0: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
68b0: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
68c0: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
68d0: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
68e0: 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65 64 20   xOpen reported 
68f0: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
6900: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
6910: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
6920: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
6930: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
6940: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f 72 20  xOpen.** is for 
6950: 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73 65 74  the xOpen to set
6960: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
6970: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
6980: 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  nt to NULL..**.*
6990: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
69a0: 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61  ment to xSync ma
69b0: 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c  y be one of [SQL
69c0: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d  ITE_SYNC_NORMAL]
69d0: 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53   or.** [SQLITE_S
69e0: 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20  YNC_FULL].  The 
69f0: 66 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20  first choice is 
6a00: 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63  the normal fsync
6a10: 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ()..** The secon
6a20: 64 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61  d choice is a Ma
6a30: 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c  c OS X style ful
6a40: 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c  lsync.  The [SQL
6a50: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
6a60: 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62  Y].** flag may b
6a70: 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64  e ORed in to ind
6a80: 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20  icate that only 
6a90: 74 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20  the data of the 
6aa0: 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20  file.** and not 
6ab0: 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20  its inode needs 
6ac0: 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a  to be synced..**
6ad0: 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20  .** The integer 
6ae0: 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28  values to xLock(
6af0: 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20  ) and xUnlock() 
6b00: 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75  are one of.** <u
6b10: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
6b20: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a  TE_LOCK_NONE],.*
6b30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6b40: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
6b50: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6b60: 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20  K_RESERVED],.** 
6b70: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
6b80: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a  K_PENDING], or.*
6b90: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6ba0: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a  OCK_EXCLUSIVE]..
6bb0: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63  ** </ul>.** xLoc
6bc0: 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68  k() increases th
6bd0: 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28  e lock. xUnlock(
6be0: 29 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20  ) decreases the 
6bf0: 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68  lock..** The xCh
6c00: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28  eckReservedLock(
6c10: 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20  ) method checks 
6c20: 77 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61  whether any data
6c30: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
6c40: 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68  .** either in th
6c50: 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e  is process or in
6c60: 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63   some other proc
6c70: 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20  ess, is holding 
6c80: 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50  a RESERVED,.** P
6c90: 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55  ENDING, or EXCLU
6ca0: 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  SIVE lock on the
6cb0: 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72   file.  It retur
6cc0: 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75  ns true.** if su
6cd0: 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73  ch a lock exists
6ce0: 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72   and false other
6cf0: 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  wise..**.** The 
6d00: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
6d10: 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72  ethod is a gener
6d20: 69 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ic interface tha
6d30: 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a  t allows custom.
6d40: 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ** VFS implement
6d50: 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74  ations to direct
6d60: 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70  ly control an op
6d70: 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68  en file using th
6d80: 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  e.** [sqlite3_fi
6d90: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e  le_control()] in
6da0: 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65  terface.  The se
6db0: 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65  cond "op" argume
6dc0: 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65  nt is an.** inte
6dd0: 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65  ger opcode.  The
6de0: 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
6df0: 69 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69  is a generic poi
6e00: 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f  nter intended to
6e10: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  .** point to a s
6e20: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61  tructure that ma
6e30: 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65  y contain argume
6e40: 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20  nts or space in 
6e50: 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74  which to.** writ
6e60: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e  e return values.
6e70: 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73    Potential uses
6e80: 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f   for xFileContro
6e90: 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20  l() might be.** 
6ea0: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61  functions to ena
6eb0: 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63  ble blocking loc
6ec0: 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73  ks with timeouts
6ed0: 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a  , to change the.
6ee0: 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74  ** locking strat
6ef0: 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  egy (for example
6f00: 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65   to use dot-file
6f10: 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75   locks), to inqu
6f20: 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65  ire.** about the
6f30: 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63   status of a loc
6f40: 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73  k, or to break s
6f50: 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65  tale locks.  The
6f60: 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20   SQLite.** core 
6f70: 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63  reserves all opc
6f80: 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31  odes less than 1
6f90: 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75  00 for its own u
6fa0: 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45  se..** A [SQLITE
6fb0: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
6fc0: 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64   | list of opcod
6fd0: 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30  es] less than 10
6fe0: 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a  0 is available..
6ff0: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
7000: 74 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75  that define a cu
7010: 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f  stom xFileContro
7020: 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20  l method should 
7030: 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67  use opcodes.** g
7040: 72 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20  reater than 100 
7050: 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63  to avoid conflic
7060: 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65  ts.  VFS impleme
7070: 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a  ntations should.
7080: 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
7090: 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20  E_NOTFOUND] for 
70a0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63  file control opc
70b0: 6f 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64  odes that they d
70c0: 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69  o not.** recogni
70d0: 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  ze..**.** The xS
70e0: 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68  ectorSize() meth
70f0: 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73  od returns the s
7100: 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68  ector size of th
7110: 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74  e.** device that
7120: 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66   underlies the f
7130: 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72  ile.  The sector
7140: 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20   size is the.** 
7150: 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68  minimum write th
7160: 61 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72  at can be perfor
7170: 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74  med without dist
7180: 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  urbing.** other 
7190: 62 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c  bytes in the fil
71a0: 65 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43  e.  The xDeviceC
71b0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29  haracteristics()
71c0: 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72  .** method retur
71d0: 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20  ns a bit vector 
71e0: 64 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76  describing behav
71f0: 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75  iors of the.** u
7200: 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65  nderlying device
7210: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
7220: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7230: 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c  AP_ATOMIC].** <l
7240: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7250: 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c  _ATOMIC512].** <
7260: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7270: 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c  P_ATOMIC1K].** <
7280: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7290: 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c  P_ATOMIC2K].** <
72a0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
72b0: 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c  P_ATOMIC4K].** <
72c0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
72d0: 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c  P_ATOMIC8K].** <
72e0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
72f0: 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20  P_ATOMIC16K].** 
7300: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7310: 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a  AP_ATOMIC32K].**
7320: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7330: 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a  CAP_ATOMIC64K].*
7340: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7350: 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44  OCAP_SAFE_APPEND
7360: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
7370: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
7380: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  AL].** </ul>.**.
7390: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
73a0: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
73b0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
73c0: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
73d0: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
73e0: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
73f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
7400: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
7410: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
7420: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
7430: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
7440: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
7450: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
7460: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
7470: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
7480: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
7490: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
74a0: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
74b0: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
74c0: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
74d0: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
74e0: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
74f0: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
7500: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
7510: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
7520: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
7530: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
7540: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
7550: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
7560: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
7570: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
7580: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
7590: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
75a0: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
75b0: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
75c0: 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20  xWrite()..**.** 
75d0: 49 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72  If xRead() retur
75e0: 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ns SQLITE_IOERR_
75f0: 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75  SHORT_READ it mu
7600: 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20  st also fill.** 
7610: 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f  in the unread po
7620: 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75  rtions of the bu
7630: 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e  ffer with zeros.
7640: 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20    A VFS that.** 
7650: 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69  fails to zero-fi
7660: 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d  ll short reads m
7670: 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72  ight seem to wor
7680: 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  k.  However,.** 
7690: 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d  failure to zero-
76a0: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
76b0: 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79   will eventually
76c0: 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61   lead to.** data
76d0: 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e  base corruption.
76e0: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
76f0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
7700: 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f  thods sqlite3_io
7710: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
7720: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7730: 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ods {.  int iVer
7740: 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
7750: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69  lose)(sqlite3_fi
7760: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  le*);.  int (*xR
7770: 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ead)(sqlite3_fil
7780: 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  e*, void*, int i
7790: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
77a0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
77b0: 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74   (*xWrite)(sqlit
77c0: 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20  e3_file*, const 
77d0: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
77e0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
77f0: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
7800: 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65  Truncate)(sqlite
7810: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
7820: 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20  _int64 size);.  
7830: 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
7840: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7850: 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  flags);.  int (*
7860: 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74  xFileSize)(sqlit
7870: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
7880: 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b  3_int64 *pSize);
7890: 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28  .  int (*xLock)(
78a0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
78b0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  nt);.  int (*xUn
78c0: 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  lock)(sqlite3_fi
78d0: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
78e0: 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65   (*xCheckReserve
78f0: 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  dLock)(sqlite3_f
7900: 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f  ile*, int *pResO
7910: 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  ut);.  int (*xFi
7920: 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74  leControl)(sqlit
7930: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70  e3_file*, int op
7940: 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20  , void *pArg);. 
7950: 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69   int (*xSectorSi
7960: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
7970: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76  *);.  int (*xDev
7980: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
7990: 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  cs)(sqlite3_file
79a0: 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  *);.  /* Methods
79b0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
79c0: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a   for version 1 *
79d0: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61  /.  int (*xShmMa
79e0: 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  p)(sqlite3_file*
79f0: 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70  , int iPg, int p
7a00: 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76  gsz, int, void v
7a10: 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e  olatile**);.  in
7a20: 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71  t (*xShmLock)(sq
7a30: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7a40: 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20   offset, int n, 
7a50: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f  int flags);.  vo
7a60: 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72  id (*xShmBarrier
7a70: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
7a80: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e  ;.  int (*xShmUn
7a90: 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  map)(sqlite3_fil
7aa0: 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c  e*, int deleteFl
7ab0: 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  ag);.  /* Method
7ac0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
7ad0: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20  d for version 2 
7ae0: 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  */.  /* Addition
7af0: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
7b00: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
7b10: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
7b20: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
7b30: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
7b40: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a  Control Opcodes.
7b50: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
7b60: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
7b70: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
7b80: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
7b90: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
7ba0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
7bb0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
7bc0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
7bd0: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
7be0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
7bf0: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
7c00: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
7c10: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
7c20: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
7c30: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
7c40: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
7c50: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
7c60: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
7c70: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
7c80: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
7c90: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
7ca0: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
7cb0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
7cc0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
7cd0: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
7ce0: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
7cf0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
7d00: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
7d10: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
7d20: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
7d30: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
7d40: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
7d50: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
7d60: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
7d70: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
7d80: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
7d90: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
7da0: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
7db0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
7dc0: 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65  IZE_HINT] opcode
7dd0: 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69   is used by SQLi
7de0: 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56  te to give the V
7df0: 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69  FS.** layer a hi
7e00: 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20  nt of how large 
7e10: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
7e20: 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62  e will grow to b
7e30: 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20  e during the.** 
7e40: 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74  current transact
7e50: 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20  ion.  This hint 
7e60: 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  is not guarantee
7e70: 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65  d to be accurate
7e80: 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66   but it.** is of
7e90: 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20  ten close.  The 
7ea0: 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d  underlying VFS m
7eb0: 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70  ight choose to p
7ec0: 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62  reallocate datab
7ed0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63  ase.** file spac
7ee0: 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20  e based on this 
7ef0: 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f  hint in order to
7f00: 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20   help writes to 
7f10: 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
7f20: 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e  file run faster.
7f30: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
7f40: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
7f50: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
7f60: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
7f70: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
7f80: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
7f90: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
7fa0: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
7fb0: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
7fc0: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
7fd0: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
7fe0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
7ff0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8000: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
8010: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
8020: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
8030: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
8040: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
8050: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
8060: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
8070: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
8080: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
8090: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
80a0: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
80b0: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
80c0: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
80d0: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
80e0: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
80f0: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
8100: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
8110: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8120: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
8130: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8140: 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e  to obtain a poin
8150: 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73  ter.** to the [s
8160: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
8170: 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77  ect associated w
8180: 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
8190: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
81a0: 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68  nection.  See th
81b0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
81c0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d  control()] docum
81d0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
81e0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
81f0: 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 28  mation..**.** ^(
8200: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8210: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20  L_SYNC_OMITTED] 
8220: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
8230: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
8240: 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  y.** SQLite and 
8250: 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65  sent to all VFSe
8260: 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20  s in place of a 
8270: 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e  call to the xSyn
8280: 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e  c method.** when
8290: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
82a0: 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52  nnection has [PR
82b0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
82c0: 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a  ] set to OFF.)^.
82d0: 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69  ** Some speciali
82e0: 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74  zed VFSes need t
82f0: 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72  his signal in or
8300: 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63  der to operate c
8310: 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e  orrectly.** when
8320: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
8330: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79  nous | PRAGMA sy
8340: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69  nchronous=OFF] i
8350: 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20  s set, but most 
8360: 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74  .** VFSes do not
8370: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
8380: 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c  l and should sil
8390: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
83a0: 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70  s opcode..** App
83b0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
83c0: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74   not call [sqlit
83d0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
83e0: 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20  )] with this.** 
83f0: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
8400: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
8410: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
8420: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
8430: 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f  VFSes.** that do
8440: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
8450: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8460: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8470: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
8480: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
8490: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
84a0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
84b0: 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _SET_LOCKPROXYFI
84c0: 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e  LE      3.#defin
84d0: 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52  e SQLITE_LAST_ER
84e0: 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20  RNO             
84f0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
8500: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
8510: 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
8520: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43  e SQLITE_FCNTL_C
8530: 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20  HUNK_SIZE       
8540: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
8550: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
8560: 54 45 52 20 20 20 20 20 37 0a 23 64 65 66 69 6e  TER     7.#defin
8570: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
8580: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
8590: 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
85a0: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65  EF: Mutex Handle
85b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
85c0: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
85d0: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
85e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
85f0: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
8600: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
8610: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
8620: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
8630: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
8640: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
8650: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
8660: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
8670: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
8680: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
8690: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
86a0: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
86b0: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
86c0: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
86d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
86e0: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
86f0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
8700: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
8710: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
8720: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
8730: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
8740: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
8750: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
8760: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
8770: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
8780: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
8790: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
87a0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
87b0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
87c0: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
87d0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
87e0: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
87f0: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
8800: 20 73 79 73 74 65 6d 22 2e 0a 2a 2a 0a 2a 2a 20   system"..**.** 
8810: 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  The value of the
8820: 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20   iVersion field 
8830: 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62  is initially 1 b
8840: 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72  ut may be larger
8850: 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65   in.** future ve
8860: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
8870: 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69  .  Additional fi
8880: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
8890: 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20  nded to this.** 
88a0: 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20  object when the 
88b0: 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69  iVersion value i
88c0: 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f  s increased.  No
88d0: 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75  te that the stru
88e0: 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20  cture.** of the 
88f0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
8900: 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ct changes in th
8910: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65  e transaction be
8920: 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20  tween.** SQLite 
8930: 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e  version 3.5.9 an
8940: 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20  d 3.6.0 and yet 
8950: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
8960: 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f  ld was not.** mo
8970: 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  dified..**.** Th
8980: 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64  e szOsFile field
8990: 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
89a0: 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b  the subclassed [
89b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a  sqlite3_file].**
89c0: 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20   structure used 
89d0: 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78  by this VFS.  mx
89e0: 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20  Pathname is the 
89f0: 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
8a00: 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20  f.** a pathname 
8a10: 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a  in this VFS..**.
8a20: 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71  ** Registered sq
8a30: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
8a40: 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20  s are kept on a 
8a50: 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d  linked list form
8a60: 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65  ed by.** the pNe
8a70: 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65  xt pointer.  The
8a80: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65   [sqlite3_vfs_re
8a90: 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64  gister()].** and
8aa0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e   [sqlite3_vfs_un
8ab0: 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65  register()] inte
8ac0: 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68  rfaces manage th
8ad0: 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20  is list.** in a 
8ae0: 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e  thread-safe way.
8af0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
8b00: 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72  fs_find()] inter
8b10: 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73  face.** searches
8b20: 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74   the list.  Neit
8b30: 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  her the applicat
8b40: 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65  ion code nor the
8b50: 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   VFS.** implemen
8b60: 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73  tation should us
8b70: 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  e the pNext poin
8b80: 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  ter..**.** The p
8b90: 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68  Next field is th
8ba0: 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20  e only field in 
8bb0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a  the sqlite3_vfs.
8bc0: 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61  ** structure tha
8bd0: 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76  t SQLite will ev
8be0: 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69  er modify.  SQLi
8bf0: 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63  te will only acc
8c00: 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79  ess.** or modify
8c10: 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c   this field whil
8c20: 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74  e holding a part
8c30: 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75  icular static mu
8c40: 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  tex..** The appl
8c50: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
8c60: 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74  ever modify anyt
8c70: 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20  hing within the 
8c80: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f  sqlite3_vfs.** o
8c90: 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f  bject once the o
8ca0: 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72  bject has been r
8cb0: 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a  egistered..**.**
8cc0: 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64   The zName field
8cd0: 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20   holds the name 
8ce0: 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c  of the VFS modul
8cf0: 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73  e.  The name mus
8d00: 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61  t.** be unique a
8d10: 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f  cross all VFS mo
8d20: 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  dules..**.** ^SQ
8d30: 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20  Lite guarantees 
8d40: 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61  that the zFilena
8d50: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
8d60: 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68  xOpen.** is eith
8d70: 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  er a NULL pointe
8d80: 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61  r or string obta
8d90: 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75  ined.** from xFu
8da0: 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74  llPathname() wit
8db0: 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75  h an optional su
8dc0: 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e  ffix added..** ^
8dd0: 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61  If a suffix is a
8de0: 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c  dded to the zFil
8df0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c  ename parameter,
8e00: 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73   it will.** cons
8e10: 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  ist of a single 
8e20: 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f  "-" character fo
8e30: 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72  llowed by no mor
8e40: 65 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c 70  e than.** 10 alp
8e50: 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72  hanumeric and/or
8e60: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e   "-" characters.
8e70: 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74  .** ^SQLite furt
8e80: 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74  her guarantees t
8e90: 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  hat.** the strin
8ea0: 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  g will be valid 
8eb0: 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e  and unchanged un
8ec0: 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a  til xClose() is.
8ed0: 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75  ** called. Becau
8ee0: 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f  se of the previo
8ef0: 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20  us sentence,.** 
8f00: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8f10: 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74  e] can safely st
8f20: 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ore a pointer to
8f30: 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65   the.** filename
8f40: 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20   if it needs to 
8f50: 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c  remember the fil
8f60: 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72  ename for some r
8f70: 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65  eason..** If the
8f80: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
8f90: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73  eter to xOpen is
8fa0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
8fb0: 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75  then xOpen.** mu
8fc0: 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77  st invent its ow
8fd0: 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65  n temporary name
8fe0: 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20   for the file.  
8ff0: 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a  ^Whenever the .*
9000: 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  * xFilename para
9010: 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74  meter is NULL it
9020: 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68   will also be th
9030: 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a  e case that the.
9040: 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74  ** flags paramet
9050: 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20  er will include 
9060: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
9070: 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a  ETEONCLOSE]..**.
9080: 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67  ** The flags arg
9090: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29  ument to xOpen()
90a0: 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69   includes all bi
90b0: 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65  ts set in.** the
90c0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
90d0: 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
90e0: 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b  _v2()].  Or if [
90f0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
9100: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f  ** or [sqlite3_o
9110: 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64  pen16()] is used
9120: 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63  , then flags inc
9130: 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a  ludes at least.*
9140: 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  * [SQLITE_OPEN_R
9150: 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c  EADWRITE] | [SQL
9160: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
9170: 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29  . .** If xOpen()
9180: 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65   opens a file re
9190: 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20  ad-only then it 
91a0: 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20  sets *pOutFlags 
91b0: 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53  to.** include [S
91c0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
91d0: 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74  NLY].  Other bit
91e0: 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20  s in *pOutFlags 
91f0: 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a  may be set..**.*
9200: 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20  * ^(SQLite will 
9210: 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20  also add one of 
9220: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c  the following fl
9230: 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e  ags to the xOpen
9240: 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65  ().** call, depe
9250: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a  nding on the obj
9260: 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64  ect being opened
9270: 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
9280: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
9290: 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c  EN_MAIN_DB].** <
92a0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
92b0: 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a  N_MAIN_JOURNAL].
92c0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
92d0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a  _OPEN_TEMP_DB].*
92e0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
92f0: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
9300: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
9310: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
9320: 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  NT_DB].** <li>  
9330: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42  [SQLITE_OPEN_SUB
9340: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
9350: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
9360: 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  ASTER_JOURNAL].*
9370: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
9380: 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75  OPEN_WAL].** </u
9390: 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  l>)^.**.** The f
93a0: 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e  ile I/O implemen
93b0: 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74  tation can use t
93c0: 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66  he object type f
93d0: 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67  lags to.** chang
93e0: 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61  e the way it dea
93f0: 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20  ls with files.  
9400: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20  For example, an 
9410: 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74  application.** t
9420: 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  hat does not car
9430: 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65  e about crash re
9440: 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61  covery or rollba
9450: 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a  ck might make.**
9460: 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a   the open of a j
9470: 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f  ournal file a no
9480: 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20  -op.  Writes to 
9490: 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75  this journal wou
94a0: 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f  ld.** also be no
94b0: 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74  -ops, and any at
94c0: 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68  tempt to read th
94d0: 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20  e journal would 
94e0: 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45  return.** SQLITE
94f0: 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20  _IOERR.  Or the 
9500: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d  implementation m
9510: 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74  ight recognize t
9520: 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a  hat a database.*
9530: 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64  * file will be d
9540: 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65  oing page-aligne
9550: 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61  d sector reads a
9560: 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72  nd writes in a r
9570: 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61  andom.** order a
9580: 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f  nd set up its I/
9590: 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f  O subsystem acco
95a0: 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  rdingly..**.** S
95b0: 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f  QLite might also
95c0: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
95d0: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
95e0: 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  to the xOpen met
95f0: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
9600: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
9610: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
9620: 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  SE].** <li> [SQL
9630: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
9640: 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VE].** </ul>.**.
9650: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ** The [SQLITE_O
9660: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
9670: 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68  E] flag means th
9680: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65  e file should be
9690: 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e  .** deleted when
96a0: 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20   it is closed.  
96b0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
96c0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
96d0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20  .** will be set 
96e0: 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73  for TEMP databas
96f0: 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75  es and their jou
9700: 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74  rnals, transient
9710: 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61  .** databases, a
9720: 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a  nd subjournals..
9730: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
9740: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
9750: 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79  E] flag is alway
9760: 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e  s used in conjun
9770: 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68  ction.** with th
9780: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  e [SQLITE_OPEN_C
9790: 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69  REATE] flag, whi
97a0: 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65  ch are both dire
97b0: 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75  ctly.** analogou
97c0: 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20  s to the O_EXCL 
97d0: 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67  and O_CREAT flag
97e0: 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f  s of the POSIX o
97f0: 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54  pen().** API.  T
9800: 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45  he SQLITE_OPEN_E
9810: 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77  XCLUSIVE flag, w
9820: 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20  hen paired with 
9830: 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  the .** SQLITE_O
9840: 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75  PEN_CREATE, is u
9850: 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20  sed to indicate 
9860: 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64  that file should
9870: 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72   always.** be cr
9880: 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20  eated, and that 
9890: 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69  it is an error i
98a0: 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69  f it already exi
98b0: 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69  sts..** It is <i
98c0: 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f  >not</i> used to
98d0: 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69   indicate the fi
98e0: 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65  le should be ope
98f0: 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c  ned .** for excl
9900: 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a  usive access..**
9910: 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a  .** ^At least sz
9920: 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20  OsFile bytes of 
9930: 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63  memory are alloc
9940: 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  ated by SQLite.*
9950: 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b  * to hold the  [
9960: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74  sqlite3_file] st
9970: 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61  ructure passed a
9980: 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61  s the third.** a
9990: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
99a0: 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74  .  The xOpen met
99b0: 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  hod does not hav
99c0: 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  e to.** allocate
99d0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20   the structure; 
99e0: 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66  it should just f
99f0: 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65  ill it in.  Note
9a00: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70   that.** the xOp
9a10: 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73  en method must s
9a20: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
9a30: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20  ile.pMethods to 
9a40: 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69  either.** a vali
9a50: 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  d [sqlite3_io_me
9a60: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72  thods] object or
9a70: 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e   to NULL.  xOpen
9a80: 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73   must do.** this
9a90: 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65   even if the ope
9aa0: 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65  n fails.  SQLite
9ab0: 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68   expects that th
9ac0: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
9ad0: 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65  Methods.** eleme
9ae0: 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  nt will be valid
9af0: 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74   after xOpen ret
9b00: 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20  urns regardless 
9b10: 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a  of the success.*
9b20: 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20  * or failure of 
9b30: 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a  the xOpen call..
9b40: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  **.** ^The flags
9b50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
9b60: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
9b70: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
9b80: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
9b90: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
9ba0: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
9bb0: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
9bc0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
9bd0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
9be0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
9bf0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
9c00: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
9c10: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
9c20: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
9c30: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
9c40: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
9c50: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
9c60: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
9c70: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
9c80: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
9c90: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
9ca0: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
9cb0: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
9cc0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
9cd0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
9ce0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
9cf0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
9d00: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
9d10: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
9d20: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
9d30: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
9d40: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
9d50: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
9d60: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
9d70: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
9d80: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
9d90: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
9da0: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
9db0: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
9dc0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
9dd0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
9de0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
9df0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
9e00: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
9e10: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
9e20: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
9e30: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
9e40: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
9e50: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
9e60: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
9e70: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
9e80: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
9e90: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
9ea0: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
9eb0: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
9ec0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
9ed0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
9ee0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
9ef0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
9f00: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
9f10: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
9f20: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
9f30: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
9f40: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
9f50: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
9f60: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
9f70: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
9f80: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
9f90: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
9fa0: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
9fb0: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
9fc0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
9fd0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
9fe0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
9ff0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
a000: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
a010: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
a020: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
a030: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
a040: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
a050: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
a060: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
a070: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
a080: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
a090: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
a0a0: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
a0b0: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
a0c0: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 65   Number multiple
a0d0: 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74  d by 86400000 (t
a0e0: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
a0f0: 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a  liseconds in .**
a100: 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e   a 24-hour day).
a110: 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69    .** ^SQLite wi
a120: 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72  ll use the xCurr
a130: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d  entTimeInt64() m
a140: 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65  ethod to get the
a150: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65   current.** date
a160: 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61   and time if tha
a170: 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69  t method is avai
a180: 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69  lable (if iVersi
a190: 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67  on is 2 or .** g
a1a0: 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66  reater and the f
a1b0: 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20  unction pointer 
a1c0: 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64  is not NULL) and
a1d0: 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a   will fall back.
a1e0: 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69  ** to xCurrentTi
a1f0: 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74  me() if xCurrent
a200: 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75  TimeInt64() is u
a210: 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a  navailable..**.*
a220: 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65  * ^The xSetSyste
a230: 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73  mCall(), xGetSys
a240: 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78  temCall(), and x
a250: 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29  NestSystemCall()
a260: 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61   interfaces.** a
a270: 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74  re not used by t
a280: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20  he SQLite core. 
a290: 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20   These optional 
a2a0: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70  interfaces are p
a2b0: 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f  rovided.** by so
a2c0: 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69  me VFSes to faci
a2d0: 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f  litate testing o
a2e0: 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20  f the VFS code. 
a2f0: 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a  By overriding .*
a300: 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77  * system calls w
a310: 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e  ith functions un
a320: 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c  der its control,
a330: 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20   a test program 
a340: 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20  can.** simulate 
a350: 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72  faults and error
a360: 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74   conditions that
a370: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
a380: 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a   be difficult.**
a390: 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74   or impossible t
a3a0: 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73  o induce.  The s
a3b0: 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c  et of system cal
a3c0: 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f  ls that can be o
a3d0: 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72  verridden.** var
a3e0: 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53  ies from one VFS
a3f0: 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64   to another, and
a400: 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f   from one versio
a410: 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46  n of the same VF
a420: 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74  S to the.** next
a430: 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
a440: 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69  that use these i
a450: 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62  nterfaces must b
a460: 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61  e prepared for a
a470: 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20  ny.** or all of 
a480: 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
a490: 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66   to be NULL or f
a4a0: 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f  or their behavio
a4b0: 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66  r to change.** f
a4c0: 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20  rom one release 
a4d0: 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70  to the next.  Ap
a4e0: 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20  plications must 
a4f0: 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61  not attempt to a
a500: 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20  ccess.** any of 
a510: 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66  these methods if
a520: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66   the iVersion of
a530: 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73   the VFS is less
a540: 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65   than 3..*/.type
a550: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
a560: 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76  e3_vfs sqlite3_v
a570: 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64  fs;.typedef void
a580: 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61   (*sqlite3_sysca
a590: 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73  ll_ptr)(void);.s
a5a0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
a5b0: 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69  s {.  int iVersi
a5c0: 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  on;            /
a5d0: 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73  * Structure vers
a5e0: 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72  ion number (curr
a5f0: 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e  ently 3) */.  in
a600: 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20  t szOsFile;     
a610: 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f         /* Size o
a620: 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c  f subclassed sql
a630: 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69  ite3_file */.  i
a640: 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20  nt mxPathname;  
a650: 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
a660: 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65  um file pathname
a670: 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c   length */.  sql
a680: 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b  ite3_vfs *pNext;
a690: 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65        /* Next re
a6a0: 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a  gistered VFS */.
a6b0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
a6c0: 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61  ame;       /* Na
a6d0: 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75  me of this virtu
a6e0: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a  al file system *
a6f0: 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
a700: 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ta;          /* 
a710: 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69  Pointer to appli
a720: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
a730: 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  data */.  int (*
a740: 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76  xOpen)(sqlite3_v
a750: 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
a760: 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f  *zName, sqlite3_
a770: 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20  file*,.         
a780: 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c        int flags,
a790: 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29   int *pOutFlags)
a7a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74  ;.  int (*xDelet
a7b0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
a7c0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
a7d0: 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29  me, int syncDir)
a7e0: 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73  ;.  int (*xAcces
a7f0: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
a800: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
a810: 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69  me, int flags, i
a820: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
a830: 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e  int (*xFullPathn
a840: 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ame)(sqlite3_vfs
a850: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
a860: 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20  Name, int nOut, 
a870: 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76  char *zOut);.  v
a880: 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28  oid *(*xDlOpen)(
a890: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
a8a0: 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
a8b0: 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ame);.  void (*x
a8c0: 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33  DlError)(sqlite3
a8d0: 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65  _vfs*, int nByte
a8e0: 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29  , char *zErrMsg)
a8f0: 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c  ;.  void (*(*xDl
a900: 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73  Sym)(sqlite3_vfs
a910: 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63  *,void*, const c
a920: 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76  har *zSymbol))(v
a930: 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  oid);.  void (*x
a940: 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33  DlClose)(sqlite3
a950: 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20  _vfs*, void*);. 
a960: 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65   int (*xRandomne
a970: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
a980: 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
a990: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20  r *zOut);.  int 
a9a0: 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65  (*xSleep)(sqlite
a9b0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72  3_vfs*, int micr
a9c0: 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74  oseconds);.  int
a9d0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29   (*xCurrentTime)
a9e0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64  (sqlite3_vfs*, d
a9f0: 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28  ouble*);.  int (
aa00: 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28  *xGetLastError)(
aa10: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
aa20: 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a  t, char *);.  /*
aa30: 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
aa40: 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
aa50: 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20  ersion 1 of the 
aa60: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
aa70: 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f  t.  ** definitio
aa80: 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66  n.  Those that f
aa90: 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20  ollow are added 
aaa0: 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20  in version 2 or 
aab0: 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74  later.  */.  int
aac0: 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49   (*xCurrentTimeI
aad0: 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66  nt64)(sqlite3_vf
aae0: 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  s*, sqlite3_int6
aaf0: 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  4*);.  /*.  ** T
ab00: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
ab10: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
ab20: 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20   1 and 2 of the 
ab30: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
ab40: 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65  t..  ** Those be
ab50: 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
ab60: 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65  ion 3 and greate
ab70: 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  r..  */.  int (*
ab80: 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xSetSystemCall)(
ab90: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
aba0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
abb0: 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
abc0: 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33  _ptr);.  sqlite3
abd0: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78  _syscall_ptr (*x
abe0: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  GetSystemCall)(s
abf0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
ac00: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
ac10: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28  .  const char *(
ac20: 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c  *xNextSystemCall
ac30: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ac40: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
ac50: 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  e);.  /*.  ** Th
ac60: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
ac70: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
ac80: 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74  1 through 3 of t
ac90: 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62  he sqlite_vfs ob
aca0: 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66  ject..  ** New f
acb0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
acc0: 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20  ended in figure 
acd0: 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69  versions.  The i
ace0: 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c  Version.  ** val
acf0: 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e  ue will incremen
ad00: 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20  t whenever this 
ad10: 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d  happens. .  */.}
ad20: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
ad30: 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
ad40: 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74   xAccess VFS met
ad50: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
ad60: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
ad70: 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73  s can be used as
ad80: 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
ad90: 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78  eter to.** the x
ada0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  Access method of
adb0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73   an [sqlite3_vfs
adc0: 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20  ] object.  They 
add0: 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61  determine.** wha
ade0: 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73  t kind of permis
adf0: 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73  sions the xAcces
ae00: 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b  s method is look
ae10: 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68  ing for..** With
ae20: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45   SQLITE_ACCESS_E
ae30: 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65  XISTS, the xAcce
ae40: 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d  ss method.** sim
ae50: 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68  ply checks wheth
ae60: 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73  er the file exis
ae70: 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  ts..** With SQLI
ae80: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
ae90: 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73  ITE, the xAccess
aea0: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
aeb0: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61  s whether the na
aec0: 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73  med directory is
aed0: 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61   both readable a
aee0: 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28  nd writable.** (
aef0: 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  in other words, 
af00: 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20  if files can be 
af10: 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20  added, removed, 
af20: 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68  and renamed with
af30: 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74  in.** the direct
af40: 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ory)..** The SQL
af50: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
af60: 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73  RITE constant is
af70: 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20   currently used 
af80: 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b  only by the.** [
af90: 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
afa0: 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68  tory pragma], th
afb0: 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20  ough this could 
afc0: 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
afd0: 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
afe0: 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68   SQLite..** With
aff0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
b000: 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73  EAD, the xAccess
b010: 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b   method.** check
b020: 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69  s whether the fi
b030: 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20  le is readable. 
b040: 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
b050: 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74  SS_READ constant
b060: 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79   is.** currently
b070: 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20   unused, though 
b080: 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64  it might be used
b090: 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c   in a future rel
b0a0: 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74  ease of.** SQLit
b0b0: 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
b0c0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
b0d0: 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20  TS    0.#define 
b0e0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
b0f0: 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55  ADWRITE 1   /* U
b100: 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65  sed by PRAGMA te
b110: 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
b120: 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ry */.#define SQ
b130: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
b140: 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75        2   /* Unu
b150: 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
b160: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f  PI3REF: Flags fo
b170: 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56  r the xShmLock V
b180: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
b190: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
b1a0: 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74  nstants define t
b1b0: 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69  he various locki
b1c0: 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  ng operations.**
b1d0: 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20   allowed by the 
b1e0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
b1f0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  of [sqlite3_io_m
b200: 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a  ethods].  The.**
b210: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74   following are t
b220: 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f  he only legal co
b230: 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c  mbinations of fl
b240: 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53  ags to the.** xS
b250: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a  hmLock method:.*
b260: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
b270: 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  >  SQLITE_SHM_LO
b280: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
b290: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
b2a0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
b2b0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
b2c0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20  LUSIVE.** <li>  
b2d0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
b2e0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
b2f0: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
b300: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
b310: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
b320: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e  CLUSIVE.** </ul>
b330: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f  .**.** When unlo
b340: 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20  cking, the same 
b350: 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53  SHARED or EXCLUS
b360: 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65  IVE flag must be
b370: 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20   supplied as.** 
b380: 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65  was given no the
b390: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c   corresponding l
b3a0: 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65  ock.  .**.** The
b3b0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
b3c0: 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20   can transition 
b3d0: 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
b3e0: 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a   and SHARED or.*
b3f0: 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b  * between unlock
b400: 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45  ed and EXCLUSIVE
b410: 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61  .  It cannot tra
b420: 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
b430: 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58  SHARED.** and EX
b440: 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66  CLUSIVE..*/.#def
b450: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  ine SQLITE_SHM_U
b460: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64  NLOCK       1.#d
b470: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
b480: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a  _LOCK         2.
b490: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
b4a0: 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  HM_SHARED       
b4b0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
b4c0: 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20  _SHM_EXCLUSIVE  
b4d0: 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    8../*.** CAPI3
b4e0: 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68  REF: Maximum xSh
b4f0: 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a  mLock index.**.*
b500: 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  * The xShmLock m
b510: 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65  ethod on [sqlite
b520: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61  3_io_methods] ma
b530: 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20  y use values.** 
b540: 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
b550: 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  is upper bound a
b560: 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61  s its "offset" a
b570: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20  rgument..** The 
b580: 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c  SQLite core will
b590: 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74   never attempt t
b5a0: 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c  o acquire or rel
b5b0: 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f  ease a.** lock o
b5c0: 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72  utside of this r
b5d0: 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ange.*/.#define 
b5e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b  SQLITE_SHM_NLOCK
b5f0: 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a          8.../*.*
b600: 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74  * CAPI3REF: Init
b610: 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74  ialize The SQLit
b620: 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20  e Library.**.** 
b630: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
b640: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
b650: 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  e initializes th
b660: 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72  e.** SQLite libr
b670: 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ary.  ^The sqlit
b680: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f  e3_shutdown() ro
b690: 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63  utine.** dealloc
b6a0: 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63  ates any resourc
b6b0: 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c  es that were all
b6c0: 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65  ocated by sqlite
b6d0: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a  3_initialize()..
b6e0: 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
b6f0: 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74  s are designed t
b700: 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73  o aid in process
b710: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
b720: 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20  and.** shutdown 
b730: 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74  on embedded syst
b740: 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f  ems.  Workstatio
b750: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75  n applications u
b760: 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e  sing.** SQLite n
b770: 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e  ormally do not n
b780: 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69  eed to invoke ei
b790: 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f  ther of these ro
b7a0: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  utines..**.** A 
b7b0: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
b7c0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
b7d0: 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63  an "effective" c
b7e0: 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20  all if it is.** 
b7f0: 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
b800: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b810: 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64  e() is invoked d
b820: 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69  uring the lifeti
b830: 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f  me of.** the pro
b840: 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69  cess, or if it i
b850: 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65  s the first time
b860: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
b870: 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
b880: 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  .** following a 
b890: 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
b8a0: 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f  shutdown().  ^(O
b8b0: 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65  nly an effective
b8c0: 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69   call.** of sqli
b8d0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
b8e0: 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61   does any initia
b8f0: 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f  lization.  All o
b900: 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72  ther calls.** ar
b910: 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  e harmless no-op
b920: 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  s.)^.**.** A cal
b930: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
b940: 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65  tdown() is an "e
b950: 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
b960: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
b970: 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c  t.** call to sql
b980: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
b990: 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73  since the last s
b9a0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b9b0: 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20  e().  ^(Only.** 
b9c0: 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c  an effective cal
b9d0: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
b9e0: 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79  tdown() does any
b9f0: 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f   deinitializatio
ba00: 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20  n..** All other 
ba10: 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73  valid calls to s
ba20: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ba30: 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  ) are harmless n
ba40: 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  o-ops.)^.**.** T
ba50: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
ba60: 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63  alize() interfac
ba70: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c  e is threadsafe,
ba80: 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75   but sqlite3_shu
ba90: 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f  tdown().** is no
baa0: 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  t.  The sqlite3_
bab0: 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72  shutdown() inter
bac0: 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62  face must only b
bad0: 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a  e called from a.
bae0: 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64  ** single thread
baf0: 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74  .  All open [dat
bb00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
bb10: 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65  s] must be close
bb20: 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68  d and all.** oth
bb30: 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72  er SQLite resour
bb40: 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c  ces must be deal
bb50: 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f  located prior to
bb60: 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
bb70: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
bb80: 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68  .**.** Among oth
bb90: 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69  er things, ^sqli
bba0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
bbb0: 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20   will invoke.** 
bbc0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
bbd0: 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e  ).  Similarly, ^
bbe0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
bbf0: 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b  ().** will invok
bc00: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
bc10: 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ()..**.** ^The s
bc20: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
bc30: 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
bc40: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
bc50: 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e  on success..** ^
bc60: 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73  If for some reas
bc70: 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  on, sqlite3_init
bc80: 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62  ialize() is unab
bc90: 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65  le to initialize
bca0: 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20  .** the library 
bcb0: 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75  (perhaps it is u
bcc0: 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
bcd0: 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75  e a needed resou
bce0: 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61  rce such.** as a
bcf0: 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72   mutex) it retur
bd00: 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  ns an [error cod
bd10: 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  e] other than [S
bd20: 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a  QLITE_OK]..**.**
bd30: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
bd40: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
bd50: 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74  ne is called int
bd60: 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20  ernally by many 
bd70: 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
bd80: 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68  interfaces so th
bd90: 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  at an applicatio
bda0: 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e  n usually does n
bdb0: 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e  ot need to.** in
bdc0: 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
bdd0: 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74  tialize() direct
bde0: 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  ly.  For example
bdf0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  , [sqlite3_open(
be00: 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69  )].** calls sqli
be10: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
be20: 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c   so the SQLite l
be30: 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61  ibrary will be a
be40: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
be50: 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e  initialized when
be60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
be70: 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69  ] is called if i
be80: 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69  t has not be ini
be90: 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65  tialized.** alre
bea0: 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20  ady.  ^However, 
beb0: 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  if SQLite is com
bec0: 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b  piled with the [
bed0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
bee0: 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65  INIT].** compile
bef0: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68  -time option, th
bf00: 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63  en the automatic
bf10: 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
bf20: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a  3_initialize().*
bf30: 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e  * are omitted an
bf40: 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  d the applicatio
bf50: 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69  n must call sqli
bf60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
bf70: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69   directly.** pri
bf80: 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20  or to using any 
bf90: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
bfa0: 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78  erface.  For max
bfb0: 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79  imum portability
bfc0: 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d  ,.** it is recom
bfd0: 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
bfe0: 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20  ications always 
bff0: 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69  invoke sqlite3_i
c000: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64  nitialize().** d
c010: 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f  irectly prior to
c020: 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
c030: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
c040: 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61  e.  Future relea
c050: 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65  ses.** of SQLite
c060: 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69   may require thi
c070: 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  s.  In other wor
c080: 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72  ds, the behavior
c090: 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68   exhibited.** wh
c0a0: 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
c0b0: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
c0c0: 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54  TE_OMIT_AUTOINIT
c0d0: 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74  ] might become t
c0e0: 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65  he.** default be
c0f0: 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66  havior in some f
c100: 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
c110: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
c120: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
c130: 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  it() routine doe
c140: 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74  s operating-syst
c150: 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69  em specific.** i
c160: 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
c170: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
c180: 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65  ary.  The sqlite
c190: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f  3_os_end().** ro
c1a0: 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65  utine undoes the
c1b0: 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74   effect of sqlit
c1c0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54  e3_os_init().  T
c1d0: 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20  ypical tasks.** 
c1e0: 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65  performed by the
c1f0: 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c  se routines incl
c200: 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f  ude allocation o
c210: 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  r deallocation.*
c220: 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f  * of static reso
c230: 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a  urces, initializ
c240: 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20  ation of global 
c250: 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65  variables,.** se
c260: 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75  tting up a defau
c270: 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
c280: 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74   module, or sett
c290: 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61  ing up.** a defa
c2a0: 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
c2b0: 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  n using [sqlite3
c2c0: 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a  _config()]..**.*
c2d0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
c2e0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69  n should never i
c2f0: 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c  nvoke either sql
c300: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
c310: 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  * or sqlite3_os_
c320: 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20  end() directly. 
c330: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
c340: 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76   should only inv
c350: 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  oke.** sqlite3_i
c360: 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20  nitialize() and 
c370: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
c380: 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ().  The sqlite3
c390: 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e  _os_init().** in
c3a0: 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65  terface is calle
c3b0: 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  d automatically 
c3c0: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  by sqlite3_initi
c3d0: 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73  alize() and.** s
c3e0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
c3f0: 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c  is called by sql
c400: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
c410: 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a    Appropriate.**
c420: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
c430: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f   for sqlite3_os_
c440: 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74  init() and sqlit
c450: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61  e3_os_end().** a
c460: 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  re built into SQ
c470: 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20  Lite when it is 
c480: 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69  compiled for Uni
c490: 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f  x, Windows, or O
c4a0: 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75  S/2..** When [cu
c4b0: 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75  stom builds | bu
c4c0: 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c  ilt for other pl
c4d0: 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69  atforms].** (usi
c4e0: 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  ng the [SQLITE_O
c4f0: 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69  S_OTHER=1] compi
c500: 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
c510: 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n) the applicati
c520: 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61  on must supply a
c530: 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d   suitable implem
c540: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20  entation for.** 
c550: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
c560: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
c570: 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c  _end().  An appl
c580: 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64  ication-supplied
c590: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
c5a0: 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  on of sqlite3_os
c5b0: 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74  _init() or sqlit
c5c0: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d  e3_os_end().** m
c5d0: 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ust return [SQLI
c5e0: 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
c5f0: 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72  s and some other
c600: 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70   [error code] up
c610: 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a  on.** failure..*
c620: 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
c630: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c640: 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ize(void);.SQLIT
c650: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
c660: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
c670: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
c680: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
c690: 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
c6a0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
c6b0: 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a  s_end(void);../*
c6c0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
c6d0: 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51  nfiguring The SQ
c6e0: 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a  Lite Library.**.
c6f0: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63  ** The sqlite3_c
c700: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
c710: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
c720: 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75  e global configu
c730: 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
c740: 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f  s to SQLite in o
c750: 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c  rder to tune SQL
c760: 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69  ite to the speci
c770: 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20  fic needs of.** 
c780: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
c790: 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f    The default co
c7a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72  nfiguration is r
c7b0: 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d  ecommended for m
c7c0: 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  ost.** applicati
c7d0: 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20  ons and so this 
c7e0: 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c  routine is usual
c7f0: 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79  ly not necessary
c800: 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76  .  It is.** prov
c810: 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  ided to support 
c820: 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e  rare application
c830: 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e  s with unusual n
c840: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eeds..**.** The 
c850: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
c860: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f   interface is no
c870: 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  t threadsafe.  T
c880: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  he application.*
c890: 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68  * must insure th
c8a0: 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69  at no other SQLi
c8b0: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
c8c0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68  e invoked by oth
c8d0: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68  er.** threads wh
c8e0: 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ile sqlite3_conf
c8f0: 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ig() is running.
c900: 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73    Furthermore, s
c910: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a  qlite3_config().
c920: 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69  ** may only be i
c930: 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20  nvoked prior to 
c940: 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69  library initiali
c950: 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  zation using.** 
c960: 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
c970: 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
c980: 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c  shutdown by [sql
c990: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
c9a0: 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
c9b0: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c  _config() is cal
c9c0: 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
c9d0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
c9e0: 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b   and before.** [
c9f0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ca00: 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c  ()] then it will
ca10: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d   return SQLITE_M
ca20: 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20  ISUSE..** Note, 
ca30: 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73  however, that ^s
ca40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ca50: 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73  can be called as
ca60: 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20   part of the.** 
ca70: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
ca80: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
ca90: 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65  -defined [sqlite
caa0: 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a  3_os_init()]..**
cab0: 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
cac0: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
cad0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e  3_config() is an
cae0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
caf0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
cb00: 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67  ETHREAD | config
cb10: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20  uration option] 
cb20: 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a  that determines.
cb30: 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74 79  ** what property
cb40: 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f   of SQLite is to
cb50: 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20   be configured. 
cb60: 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
cb70: 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65  ments.** vary de
cb80: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b  pending on the [
cb90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
cba0: 4e 47 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e  NGLETHREAD | con
cbb0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
cbc0: 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
cbd0: 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
cbe0: 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
cbf0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
cc00: 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
cc10: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
cc20: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
cc30: 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
cc40: 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
cc50: 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
cc60: 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
cc70: 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
cc80: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
cc90: 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
cca0: 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  code]..*/.SQLITE
ccb0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
ccc0: 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
ccd0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
cce0: 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
ccf0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
cd00: 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
cd10: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
cd20: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
cd30: 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
cd40: 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
cd50: 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
cd60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
cd70: 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
cd80: 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
cd90: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
cda0: 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
cdb0: 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
cdc0: 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
cdd0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
cde0: 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
cdf0: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
ce00: 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
ce10: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
ce20: 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
ce30: 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
ce40: 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
ce50: 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
ce60: 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
ce70: 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
ce80: 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
ce90: 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
cea0: 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
ceb0: 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
cec0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
ced0: 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
cee0: 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
cef0: 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
cf00: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
cf10: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
cf20: 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
cf30: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
cf40: 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
cf50: 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
cf60: 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
cf70: 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
cf80: 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53  successful..*/.S
cf90: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
cfa0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
cfb0: 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70  sqlite3*, int op
cfc0: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
cfd0: 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
cfe0: 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69  Allocation Routi
cff0: 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  nes.**.** An ins
d000: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
d010: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
d020: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
d030: 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  en SQLite.** and
d040: 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
d050: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
d060: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  tines..**.** Thi
d070: 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  s object is used
d080: 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61   in only one pla
d090: 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65  ce in the SQLite
d0a0: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41   interface..** A
d0b0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
d0c0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
d0d0: 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61 72  object is the ar
d0e0: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71  gument to.** [sq
d0f0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
d100: 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75  when the configu
d110: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
d120: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
d130: 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53  IG_MALLOC] or [S
d140: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
d150: 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79  MALLOC].  .** By
d160: 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73   creating an ins
d170: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
d180: 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73  ject.** and pass
d190: 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
d1a0: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
d1b0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
d1c0: 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e  ]).** during con
d1d0: 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61  figuration, an a
d1e0: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73  pplication can s
d1f0: 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
d200: 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
d210: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
d220: 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20  stem for SQLite 
d230: 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f  to use for all o
d240: 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63  f its.** dynamic
d250: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a   memory needs..*
d260: 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
d270: 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68  QLite comes with
d280: 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d   several [built-
d290: 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
d2a0: 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72  tors].** that ar
d2b0: 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65 71  e perfectly adeq
d2c0: 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65  uate for the ove
d2d0: 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69  rwhelming majori
d2e0: 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f  ty of applicatio
d2f0: 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74  ns.** and that t
d300: 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e  his object is on
d310: 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74  ly useful to a t
d320: 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20  iny minority of 
d330: 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
d340: 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64  with specialized
d350: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d360: 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e  on requirements.
d370: 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73    This object is
d380: 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75  .** also used du
d390: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20  ring testing of 
d3a0: 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
d3b0: 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  to specify an al
d3c0: 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
d3d0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68  ory allocator th
d3e0: 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d  at simulates mem
d3f0: 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72  ory out-of-memor
d400: 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a  y conditions in.
d410: 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69  ** order to veri
d420: 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20 72  fy that SQLite r
d430: 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c  ecovers graceful
d440: 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20  ly from such.** 
d450: 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  conditions..**.*
d460: 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e  * The xMalloc an
d470: 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
d480: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
d490: 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61  he.** malloc() a
d4a0: 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
d4b0: 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
d4c0: 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
d4d0: 0a 2a 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63  .** The xRealloc
d4e0: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72   method must wor
d4f0: 6b 20 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29  k like realloc()
d500: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
d510: 72 64 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20  rd C library.** 
d520: 77 69 74 68 20 74 68 65 20 65 78 63 65 70 74 69  with the excepti
d530: 6f 6e 20 74 68 61 74 20 69 66 20 74 68 65 20 73  on that if the s
d540: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
d550: 6f 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65  o xRealloc is ze
d560: 72 6f 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20  ro,.** xRealloc 
d570: 6d 75 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20  must be a no-op 
d580: 2d 20 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65  - it must not pe
d590: 72 66 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61  rform any alloca
d5a0: 74 69 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c  tion or.** deall
d5b0: 6f 63 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74  ocation.  ^SQLit
d5c0: 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  e guarantees tha
d5d0: 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  t the second arg
d5e0: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61  ument to.** xRea
d5f0: 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61  lloc is always a
d600: 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
d610: 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20  by a prior call 
d620: 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20  to xRoundup..** 
d630: 41 6e 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20  And so in cases 
d640: 77 68 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61  where xRoundup a
d650: 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
d660: 70 6f 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c  positive number,
d670: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e  .** xRealloc can
d680: 20 70 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79   perform exactly
d690: 20 61 73 20 74 68 65 20 73 74 61 6e 64 61 72 64   as the standard
d6a0: 20 6c 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63   library realloc
d6b0: 28 29 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20  () and.** still 
d6c0: 62 65 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65  be in compliance
d6d0: 20 77 69 74 68 20 74 68 69 73 20 73 70 65 63 69   with this speci
d6e0: 66 69 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  fication..**.** 
d6f0: 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74  xSize should ret
d700: 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65  urn the allocate
d710: 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f  d size of a memo
d720: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
d730: 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61   previously obta
d740: 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f  ined from xMallo
d750: 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20  c or xRealloc.  
d760: 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  The allocated si
d770: 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ze.** is always 
d780: 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20  at least as big 
d790: 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64  as the requested
d7a0: 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65   size but may be
d7b0: 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54   larger..**.** T
d7c0: 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68  he xRoundup meth
d7d0: 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20  od returns what 
d7e0: 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c  would be the all
d7f0: 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a  ocated size of.*
d800: 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  * a memory alloc
d810: 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61  ation given a pa
d820: 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74  rticular request
d830: 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d  ed size.  Most m
d840: 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
d850: 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d  ors round up mem
d860: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  ory allocations 
d870: 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20  at least to the 
d880: 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a  next multiple.**
d890: 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c   of 8.  Some all
d8a0: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
d8b0: 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c   to a larger mul
d8c0: 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f  tiple or to a po
d8d0: 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65  wer of 2..** Eve
d8e0: 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ry memory alloca
d8f0: 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d  tion request com
d900: 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b  ing in through [
d910: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
d920: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
d930: 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73  _realloc()] firs
d940: 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70  t calls xRoundup
d950: 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72  .  If xRoundup r
d960: 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68  eturns 0, .** th
d970: 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f  at causes the co
d980: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f  rresponding memo
d990: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
d9a0: 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   fail..**.** The
d9b0: 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e   xInit method in
d9c0: 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65  itializes the me
d9d0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
d9e0: 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a   (For example,.*
d9f0: 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
da00: 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
da10: 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
da20: 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
da30: 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
da40: 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
da50: 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
da60: 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
da70: 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
da80: 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
da90: 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
daa0: 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
dab0: 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
dac0: 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
dad0: 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
dae0: 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
daf0: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
db00: 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
db10: 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
db20: 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
db30: 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
db40: 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
db50: 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
db60: 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
db70: 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
db80: 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
db90: 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
dba0: 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
dbb0: 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
dbc0: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
dbd0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
dbe0: 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
dbf0: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
dc00: 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
dc10: 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
dc20: 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
dc30: 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
dc40: 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
dc50: 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
dc60: 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
dc70: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
dc80: 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
dc90: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
dca0: 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
dcb0: 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
dcc0: 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
dcd0: 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
dce0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
dcf0: 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
dd00: 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
dd10: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
dd20: 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
dd30: 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
dd40: 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
dd50: 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
dd60: 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
dd70: 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
dd80: 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
dd90: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
dda0: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
ddb0: 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
ddc0: 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
ddd0: 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
dde0: 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
ddf0: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
de00: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
de10: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
de20: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
de30: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
de40: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
de50: 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
de60: 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
de70: 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
de80: 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
de90: 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
dea0: 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
deb0: 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
dec0: 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
ded0: 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
dee0: 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
def0: 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
df00: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
df10: 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
df20: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
df30: 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
df40: 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
df50: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
df60: 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
df70: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
df80: 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
df90: 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
dfa0: 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
dfb0: 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
dfc0: 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
dfd0: 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
dfe0: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
dff0: 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
e000: 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
e010: 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
e020: 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
e030: 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
e040: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
e050: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
e060: 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
e070: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
e080: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
e090: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
e0a0: 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
e0b0: 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
e0c0: 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
e0d0: 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
e0e0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e0f0: 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
e100: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
e110: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
e120: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
e130: 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
e140: 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
e150: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e160: 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
e170: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
e180: 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
e190: 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
e1a0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
e1b0: 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
e1c0: 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
e1d0: 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
e1e0: 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
e1f0: 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
e200: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
e210: 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
e220: 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
e230: 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
e240: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
e250: 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
e260: 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
e270: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
e280: 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
e290: 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
e2a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e2b0: 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
e2c0: 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
e2d0: 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
e2e0: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
e2f0: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
e300: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
e310: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
e320: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
e330: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
e340: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
e350: 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
e360: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
e370: 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
e380: 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
e390: 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
e3a0: 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
e3b0: 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
e3c0: 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
e3d0: 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
e3e0: 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
e3f0: 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
e400: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
e410: 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
e420: 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
e430: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
e440: 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
e450: 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
e460: 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
e470: 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
e480: 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
e490: 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
e4a0: 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
e4b0: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
e4c0: 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
e4d0: 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
e4e0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
e4f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
e500: 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
e510: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
e520: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
e530: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
e540: 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
e550: 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
e560: 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
e570: 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
e580: 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
e590: 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
e5a0: 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
e5b0: 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
e5c0: 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
e5d0: 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
e5e0: 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
e5f0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
e600: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
e610: 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
e620: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
e630: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
e640: 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
e650: 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
e660: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e670: 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
e680: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
e690: 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
e6a0: 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
e6b0: 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
e6c0: 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
e6d0: 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
e6e0: 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
e6f0: 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
e700: 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
e710: 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
e720: 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
e730: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
e740: 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
e750: 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
e760: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
e770: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
e780: 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
e790: 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
e7a0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
e7b0: 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
e7c0: 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
e7d0: 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
e7e0: 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
e7f0: 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
e800: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e810: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
e820: 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
e830: 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
e840: 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
e850: 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
e860: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e870: 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  on.</dd>.**.** <
e880: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
e890: 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e  _SERIALIZED</dt>
e8a0: 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
e8b0: 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
e8c0: 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
e8d0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
e8e0: 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
e8f0: 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72  ing mode] to Ser
e900: 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65  ialized. In othe
e910: 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70  r words, this op
e920: 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20  tion enables.** 
e930: 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c  all mutexes incl
e940: 75 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73  uding the recurs
e950: 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f  ive.** mutexes o
e960: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
e970: 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
e980: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
e990: 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20   objects..** In 
e9a0: 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68  this mode (which
e9b0: 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20   is the default 
e9c0: 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63  when SQLite is c
e9d0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
e9e0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
e9f0: 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74  FE=1]) the SQLit
ea00: 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69  e library will i
ea10: 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20  tself serialize 
ea20: 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61  access.** to [da
ea30: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ea40: 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
ea50: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f  d statements] so
ea60: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70   that the.** app
ea70: 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  lication is free
ea80: 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
ea90: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
eaa0: 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a  ction] or the.**
eab0: 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20   same [prepared 
eac0: 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69  statement] in di
ead0: 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20  fferent threads 
eae0: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
eaf0: 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20  ..** ^If SQLite 
eb00: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
eb10: 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
eb20: 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
eb30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
eb40: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
eb50: 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
eb60: 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
eb70: 20 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69   to set the Seri
eb80: 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
eb90: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
eba0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ebb0: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
ebc0: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
ebd0: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
ebe0: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
ebf0: 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66  _SERIALIZED conf
ec00: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ec10: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ec20: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
ec30: 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
ec40: 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
ec50: 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
ec60: 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
ec70: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
ec80: 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
ec90: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
eca0: 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
ecb0: 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
ecc0: 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
ecd0: 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
ece0: 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
ecf0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
ed00: 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
ed10: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
ed20: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ed30: 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
ed40: 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
ed50: 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
ed60: 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
ed70: 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
ed80: 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
ed90: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
eda0: 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
edb0: 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
edc0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
edd0: 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
ede0: 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
edf0: 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
ee00: 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
ee10: 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
ee20: 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
ee30: 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
ee40: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
ee50: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
ee60: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
ee70: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
ee80: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
ee90: 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
eea0: 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
eeb0: 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
eec0: 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
eed0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
eee0: 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
eef0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
ef00: 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
ef10: 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
ef20: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ef30: 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
ef40: 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
ef50: 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
ef60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
ef70: 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
ef80: 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
ef90: 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
efa0: 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
efb0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
efc0: 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
efd0: 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
efe0: 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
eff0: 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
f000: 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
f010: 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
f020: 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
f030: 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
f040: 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
f050: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f060: 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
f070: 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
f080: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
f090: 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
f0a0: 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
f0b0: 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
f0c0: 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
f0d0: 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
f0e0: 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
f0f0: 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
f100: 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
f110: 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
f120: 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
f130: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
f140: 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
f150: 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
f160: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
f170: 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
f180: 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
f190: 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
f1a0: 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
f1b0: 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
f1c0: 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
f1d0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
f1e0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
f1f0: 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
f200: 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
f210: 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
f220: 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
f230: 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
f240: 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
f250: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
f260: 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
f270: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
f280: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
f290: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
f2a0: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
f2b0: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
f2c0: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
f2d0: 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
f2e0: 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
f2f0: 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
f300: 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
f310: 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
f320: 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
f330: 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
f340: 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
f350: 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
f360: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
f370: 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
f380: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
f390: 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
f3a0: 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
f3b0: 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
f3c0: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
f3d0: 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a  ltiple of 16..**
f3e0: 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
f3f0: 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
f400: 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
f410: 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
f420: 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
f430: 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
f440: 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
f450: 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
f460: 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61  re than two scra
f470: 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
f480: 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e  thread.  So.** N
f490: 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
f4a0: 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65  o twice the expe
f4b0: 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
f4c0: 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a  ber of threads..
f4d0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
f4e0: 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20  never require a 
f4f0: 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
f500: 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
f510: 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
f520: 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
f530: 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  ze. ^If SQLite n
f540: 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
f550: 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
f560: 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
f570: 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
f580: 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
f590: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
f5a0: 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
f5b0: 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
f5c0: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
f5d0: 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
f5e0: 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  ed.</dd>.**.** <
f5f0: 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
f600: 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a  _PAGECACHE</dt>.
f610: 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
f620: 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
f630: 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
f640: 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
f650: 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
f660: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
f670: 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68  ge cache with th
f680: 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63  e default page c
f690: 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 61 74 69  ache implemenati
f6a0: 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
f6b0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
f6c0: 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
f6d0: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
f6e0: 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
f6f0: 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
f700: 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
f710: 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
f720: 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 6f 70  CONFIG_PCACHE op
f730: 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61  tion..** There a
f740: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
f750: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
f760: 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  n: A pointer to 
f770: 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a  8-byte aligned.*
f780: 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
f790: 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
f7a0: 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
f7b0: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
f7c0: 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
f7d0: 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
f7e0: 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
f7f0: 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
f800: 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
f810: 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
f820: 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
f830: 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69  32768) plus a li
f840: 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65  ttle extra for e
f850: 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
f860: 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68  er.  ^The page h
f870: 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30  eader size is 20
f880: 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70   to 40 bytes dep
f890: 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65  ending on.** the
f8a0: 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75   host architectu
f8b0: 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d  re.  ^It is harm
f8c0: 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d  less, apart from
f8d0: 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f   the wasted memo
f8e0: 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73  ry,.** to make s
f8f0: 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c  z a little too l
f900: 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74  arge.  The first
f910: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
f920: 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  uld point to an 
f930: 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74  allocation of at
f940: 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
f950: 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
f960: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
f970: 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
f980: 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ided by the firs
f990: 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61  t argument to sa
f9a0: 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d  tisfy its.** mem
f9b0: 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68  ory needs for th
f9c0: 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20  e first N pages 
f9d0: 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20  that it adds to 
f9e0: 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69  cache.  ^If addi
f9f0: 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
fa00: 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
fa10: 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
fa20: 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
fa30: 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68   this option, th
fa40: 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65  en.** SQLite goe
fa50: 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
fa60: 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20  lloc()] for the 
fa70: 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61  additional stora
fa80: 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65  ge space..** The
fa90: 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20   pointer in the 
faa0: 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
fab0: 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65  ust.** be aligne
fac0: 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
fad0: 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
fae0: 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
faf0: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  f SQLite.** will
fb00: 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   be undefined.</
fb10: 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
fb20: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
fb30: 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
fb40: 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
fb50: 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
fb60: 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
fb70: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
fb80: 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  .** for all of i
fb90: 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ts dynamic memor
fba0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
fbb0: 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20  ds beyond those 
fbc0: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20  provided.** for 
fbd0: 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  by [SQLITE_CONFI
fbe0: 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b  G_SCRATCH] and [
fbf0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
fc00: 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65  GECACHE]..** The
fc10: 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
fc20: 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74  uments: An 8-byt
fc30: 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65  e aligned pointe
fc40: 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c  r to the memory,
fc50: 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
fc60: 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d  f bytes in the m
fc70: 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e  emory buffer, an
fc80: 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c  d the minimum al
fc90: 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a  location size..*
fca0: 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20  * ^If the first 
fcb0: 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d  pointer (the mem
fcc0: 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20  ory pointer) is 
fcd0: 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74  NULL, then SQLit
fce0: 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20  e reverts.** to 
fcf0: 75 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c  using its defaul
fd00: 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
fd10: 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d  or (the system m
fd20: 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e  alloc() implemen
fd30: 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f  tation),.** undo
fd40: 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e  ing any prior in
fd50: 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c  vocation of [SQL
fd60: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
fd70: 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  C].  ^If the.** 
fd80: 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69  memory pointer i
fd90: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65  s not NULL and e
fda0: 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e  ither [SQLITE_EN
fdb0: 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72  ABLE_MEMSYS3] or
fdc0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  .** [SQLITE_ENAB
fdd0: 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20  LE_MEMSYS5] are 
fde0: 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68  defined, then th
fdf0: 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65  e alternative me
fe00: 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
fe10: 72 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20  r is engaged to 
fe20: 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51  handle all of SQ
fe30: 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  Lites memory all
fe40: 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a  ocation needs..*
fe50: 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e  * The first poin
fe60: 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20  ter (the memory 
fe70: 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65  pointer) must be
fe80: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
fe90: 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72  -byte.** boundar
fea0: 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20  y or subsequent 
feb0: 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69  behavior of SQLi
fec0: 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  te will be undef
fed0: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e  ined..** The min
fee0: 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
fef0: 73 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61  size is capped a
ff00: 74 20 32 5e 31 32 2e 20 52 65 61 73 6f 6e 61 62  t 2^12. Reasonab
ff10: 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
ff20: 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
ff30: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
ff40: 20 32 5e 35 20 74 68 72 6f 75 67 68 20 32 5e 38   2^5 through 2^8
ff50: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  .</dd>.**.** <dt
ff60: 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
ff70: 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
ff80: 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
ff90: 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
ffa0: 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
ffb0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
ffc0: 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
ffd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
ffe0: 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
fff0: 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
10000 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
10010 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
10020 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
10030 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
10040 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68  d in place.** th
10050 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
10060 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
10070 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
10080 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
10090 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66  he.** content of
100a0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
100b0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
100c0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
100d0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
100e0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
100f0 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
10100 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10110 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
10120 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
10130 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
10140 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
10150 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
10160 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
10170 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
10180 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
10190 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
101a0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
101b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
101c0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
101d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
101e0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
101f0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
10200 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
10210 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  R].</dd>.**.** <
10220 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10230 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
10240 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
10250 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
10260 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
10270 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
10280 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
10290 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
102a0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
102b0 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
102c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
102d0 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
102e0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
102f0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
10300 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
10310 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
10320 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
10330 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
10340 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
10350 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
10360 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
10370 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
10380 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
10390 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
103a0 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
103b0 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
103c0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
103d0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
103e0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
103f0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
10400 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
10410 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
10420 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
10430 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
10440 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
10450 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
10460 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
10470 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
10480 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
10490 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
104a0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
104b0 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
104c0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
104d0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
104e0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
104f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
10500 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
10510 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
10520 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
10530 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
10540 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
10550 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a  ine the default.
10560 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
10570 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f  tion for the loo
10580 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
10590 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a  locator on each.
105a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
105b0 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66  nection].  The f
105c0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
105d0 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
105e0 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
105f0 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
10600 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
10610 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
10620 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
10630 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
10640 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
10650 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
10660 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75   the.** <i>defau
10670 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
10680 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
10690 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
106a0 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74  ASIDE].** verb t
106b0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
106c0 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75  nfig()] can be u
106d0 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
106e0 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63  e lookaside.** c
106f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20  onfiguration on 
10700 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65  individual conne
10710 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a  ctions.)^ </dd>.
10720 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
10730 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 3c 2f  _CONFIG_PCACHE</
10740 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
10750 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
10760 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
10770 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
10780 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73  nter to.** an [s
10790 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
107a0 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20  thods] object.  
107b0 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
107c0 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
107d0 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
107e0 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
107f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20  plementation.)^ 
10800 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
10810 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
10820 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20  object and uses 
10830 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  it for page cach
10840 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
10850 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ions.</dd>.**.**
10860 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
10870 49 47 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74  IG_GETPCACHE</dt
10880 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
10890 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
108a0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
108b0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
108c0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
108d0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
108e0 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51  ods] object.  SQ
108f0 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74  Lite copies of t
10900 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61  he current.** pa
10910 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
10920 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61  ntation into tha
10930 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64  t object.)^ </dd
10940 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
10950 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
10960 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
10970 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
10980 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
10990 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
109a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
109b0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
109c0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
109d0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
109e0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
109f0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
10a00 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
10a10 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
10a20 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
10a30 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
10a40 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
10a50 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
10a60 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
10a70 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
10a80 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
10a90 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
10aa0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
10ab0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
10ac0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
10ad0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
10ae0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
10af0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
10b00 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
10b10 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
10b20 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
10b30 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
10b40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
10b50 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
10b60 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
10b70 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
10b80 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
10b90 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
10ba0 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
10bb0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
10bc0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
10bd0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
10be0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
10bf0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
10c00 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
10c10 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
10c20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
10c30 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
10c40 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
10c50 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
10c60 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
10c70 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
10c80 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
10c90 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
10ca0 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
10cb0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
10cc0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
10cd0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
10ce0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
10cf0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
10d00 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
10d10 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
10d20 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
10d30 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
10d40 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
10d50 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
10d60 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
10d70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
10d80 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
10d90 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
10da0 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
10db0 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23  **.** </dl>.*/.#
10dc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
10dd0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
10de0 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a  D  1  /* nil */.
10df0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
10e00 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
10e10 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f  D   2  /* nil */
10e20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10e30 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
10e40 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a  D    3  /* nil *
10e50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
10e60 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20  _CONFIG_MALLOC  
10e70 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69        4  /* sqli
10e80 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
10e90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
10ea0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
10eb0 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71  LOC     5  /* sq
10ec0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
10ed0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
10ee0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
10ef0 54 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20  TCH       6  /* 
10f00 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
10f10 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
10f20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
10f30 47 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f  GECACHE     7  /
10f40 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
10f50 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
10f60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
10f70 48 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20  HEAP          8 
10f80 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e   /* void*, int n
10f90 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f  Byte, int min */
10fa0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
10fb0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
10fc0 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65       9  /* boole
10fd0 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  an */.#define SQ
10fe0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
10ff0 58 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20  X        10  /* 
11000 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
11010 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
11020 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11030 47 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20  GETMUTEX     11 
11040 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
11050 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a  x_methods* */./*
11060 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49   previously SQLI
11070 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41  TE_CONFIG_CHUNKA
11080 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73  LLOC 12 which is
11090 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20   now unused. */ 
110a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
110b0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
110c0 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69      13  /* int i
110d0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
110e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
110f0 48 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20  HE       14  /* 
11100 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
11110 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
11120 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
11130 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
11140 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
11150 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  che_methods* */.
11160 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11170 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
11180 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
11190 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   void* */../*.**
111a0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
111b0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
111c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
111d0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
111e0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
111f0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
11200 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
11210 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
11220 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
11230 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
11240 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
11250 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
11260 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
11270 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
11280 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11290 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
112a0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
112b0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
112c0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
112d0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
112e0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
112f0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
11300 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
11310 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
11320 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
11330 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
11340 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
11350 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
11360 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
11370 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
11380 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
11390 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
113a0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
113b0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
113c0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
113d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
113e0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
113f0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
11400 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
11410 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
11420 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
11430 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11440 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
11450 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
11460 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
11470 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
11480 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
11490 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
114a0 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
114b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
114c0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
114d0 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
114e0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
114f0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11500 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
11510 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
11520 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
11530 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
11540 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
11550 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
11560 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
11570 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
11580 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
11590 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
115a0 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
115b0 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
115c0 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
115d0 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
115e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
115f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
11600 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
11610 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
11620 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
11630 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
11640 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
11650 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
11660 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
11670 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
11680 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
11690 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
116a0 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
116b0 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
116c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
116d0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
116e0 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
116f0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
11700 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
11710 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
11720 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
11730 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
11740 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
11750 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
11760 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
11770 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
11780 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
11790 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
117a0 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
117b0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
117c0 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
117d0 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
117e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
117f0 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
11800 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
11810 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
11820 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
11830 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
11840 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
11850 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
11860 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
11870 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
11880 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
11890 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
118a0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
118b0 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
118c0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
118d0 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
118e0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
118f0 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
11900 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
11910 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
11920 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
11930 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
11940 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
11950 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
11960 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
11970 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
11980 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
11990 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
119a0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
119b0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
119c0 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
119d0 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
119e0 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
119f0 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
11a00 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
11a10 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
11a20 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
11a30 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
11a40 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
11a50 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
11a60 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
11a70 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
11a80 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
11a90 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
11aa0 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
11ab0 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
11ac0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
11ad0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
11ae0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
11af0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
11b00 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
11b10 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
11b20 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
11b30 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
11b40 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
11b50 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
11b60 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
11b70 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
11b80 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
11b90 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
11ba0 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
11bb0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
11bc0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
11bd0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
11be0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
11bf0 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
11c00 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
11c10 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
11c20 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
11c30 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
11c40 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
11c50 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
11c60 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
11c70 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
11c80 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
11c90 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
11ca0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
11cb0 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
11cc0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
11cd0 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
11ce0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
11cf0 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
11d00 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
11d10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
11d20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
11d30 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
11d40 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
11d50 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
11d60 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
11d70 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
11d80 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
11d90 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
11da0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
11db0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
11dc0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
11dd0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
11de0 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
11df0 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
11e00 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
11e10 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
11e20 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
11e30 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
11e40 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30  KASIDE       100
11e50 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
11e60 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
11e70 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
11e80 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31  NABLE_FKEY     1
11e90 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  002  /* int int*
11ea0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11eb0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
11ec0 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33  LE_TRIGGER  1003
11ed0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
11ee0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
11ef0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
11f00 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
11f10 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
11f20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
11f30 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
11f40 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
11f50 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
11f60 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
11f70 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
11f80 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
11f90 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
11fa0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
11fb0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
11fc0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
11fd0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
11fe0 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54  bility..*/.SQLIT
11ff0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
12000 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
12010 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
12020 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
12030 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
12040 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
12050 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
12060 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
12070 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
12080 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
12090 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
120a0 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
120b0 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
120c0 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
120d0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
120e0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
120f0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
12100 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
12110 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
12120 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
12130 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
12140 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
12150 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
12160 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
12170 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
12180 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
12190 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
121a0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
121b0 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
121c0 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
121d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
121e0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
121f0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
12200 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
12210 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
12220 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
12230 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
12240 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
12250 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
12260 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
12270 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
12280 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61   [INSERT]s.** ha
12290 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
122a0 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
122b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
122c0 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
122d0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
122e0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
122f0 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 2c 20  thin a trigger, 
12300 74 68 65 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  then the [rowid]
12310 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
12320 0a 2a 2a 20 72 6f 77 20 69 73 20 72 65 74 75 72  .** row is retur
12330 6e 65 64 20 62 79 20 74 68 69 73 20 72 6f 75 74  ned by this rout
12340 69 6e 65 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ine as long as t
12350 68 65 20 74 72 69 67 67 65 72 20 69 73 20 72 75  he trigger is ru
12360 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
12370 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 74  ce the trigger t
12380 65 72 6d 69 6e 61 74 65 73 2c 20 74 68 65 20 76  erminates, the v
12390 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
123a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a 2a   this routine.**
123b0 20 72 65 76 65 72 74 73 20 74 6f 20 74 68 65 20   reverts to the 
123c0 6c 61 73 74 20 76 61 6c 75 65 20 69 6e 73 65 72  last value inser
123d0 74 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 74  ted before the t
123e0 72 69 67 67 65 72 20 66 69 72 65 64 2e 29 5e 0a  rigger fired.)^.
123f0 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
12400 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
12410 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
12420 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
12430 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
12440 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
12450 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
12460 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
12470 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
12480 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
12490 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
124a0 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
124b0 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
124c0 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
124d0 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
124e0 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
124f0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
12500 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
12510 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
12520 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
12530 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
12540 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
12550 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
12560 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
12570 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
12580 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
12590 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
125a0 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
125b0 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
125c0 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
125d0 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
125e0 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
125f0 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
12600 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
12610 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
12620 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
12630 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
12640 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
12650 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
12660 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
12670 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
12680 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
12690 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
126a0 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
126b0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
126c0 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
126d0 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
126e0 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
126f0 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
12700 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
12710 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
12720 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
12730 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
12740 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
12750 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
12760 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
12770 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
12780 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
12790 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
127a0 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
127b0 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
127c0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
127d0 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
127e0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
127f0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
12800 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
12810 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
12820 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
12830 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
12840 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
12850 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
12860 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49  [rowid]..*/.SQLI
12870 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
12880 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
12890 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
128a0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
128b0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
128c0 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
128d0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
128e0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
128f0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
12900 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
12910 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
12920 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
12930 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
12940 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
12950 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
12960 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
12970 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
12980 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
12990 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
129a0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
129b0 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
129c0 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
129d0 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
129e0 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
129f0 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
12a00 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
12a10 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
12a20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
12a30 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
12a40 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
12a50 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
12a60 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
12a70 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
12a80 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
12a90 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
12aa0 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
12ab0 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
12ac0 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
12ad0 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
12ae0 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
12af0 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
12b00 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
12b10 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
12b20 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
12b30 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
12b40 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
12b50 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
12b60 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
12b70 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
12b80 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
12b90 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
12ba0 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
12bb0 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
12bc0 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
12bd0 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
12be0 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
12bf0 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
12c00 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
12c10 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
12c20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
12c30 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
12c40 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
12c50 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
12c60 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
12c70 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
12c80 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
12c90 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
12ca0 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
12cb0 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
12cc0 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
12cd0 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
12ce0 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
12cf0 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
12d00 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
12d10 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
12d20 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
12d30 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
12d40 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
12d50 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
12d60 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
12d70 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
12d80 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
12d90 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
12da0 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
12db0 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
12dc0 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
12dd0 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
12de0 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
12df0 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
12e00 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
12e10 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
12e20 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
12e30 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
12e40 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
12e50 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
12e60 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
12e70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
12e80 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
12e90 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
12ea0 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
12eb0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
12ec0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
12ed0 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
12ee0 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
12ef0 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
12f00 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
12f10 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
12f20 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
12f30 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
12f40 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
12f50 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
12f60 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
12f70 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
12f80 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
12f90 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
12fa0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
12fb0 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
12fc0 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
12fd0 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
12fe0 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
12ff0 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
13000 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
13010 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
13020 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
13030 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
13040 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
13050 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
13060 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
13070 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
13080 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
13090 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
130a0 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
130b0 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
130c0 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
130d0 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
130e0 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
130f0 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
13100 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
13110 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
13120 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
13130 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
13140 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
13150 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
13160 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
13170 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
13180 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
13190 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
131a0 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
131b0 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
131c0 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
131d0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
131e0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
131f0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
13200 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
13210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13220 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
13230 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
13240 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
13250 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
13260 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
13270 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
13280 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
13290 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
132a0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
132b0 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
132c0 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
132d0 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
132e0 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
132f0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
13300 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
13310 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
13320 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d  used by [INSERT]
13330 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72  ,.** [UPDATE] or
13340 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
13350 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
13360 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13370 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
13380 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20  .** ^(The count 
13390 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
133a0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
133b0 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  s() includes all
133c0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d   changes.** from
133d0 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49   all [CREATE TRI
133e0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20  GGER | trigger] 
133f0 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61  contexts and cha
13400 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20  nges made by.** 
13410 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
13420 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a  ions]. However,.
13430 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
13440 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
13450 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
13460 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45  plement [REPLACE
13470 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  ] constraints,.*
13480 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
13490 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
134a0 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42  ng, or [DROP TAB
134b0 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20  LE] processing. 
134c0 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f   The.** count do
134d0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72  es not include r
134e0 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61  ows of views tha
134f0 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45  t fire an [INSTE
13500 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a  AD OF trigger],.
13510 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65  ** though if the
13520 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
13530 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ger makes change
13540 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68  s of its own, th
13550 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20  ose changes .** 
13560 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a  are counted.)^.*
13570 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
13580 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66  otal_changes() f
13590 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74  unction counts t
135a0 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f  he changes as so
135b0 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61  on as.** the sta
135c0 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
135d0 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
135e0 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
135f0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a  atement handle.*
13600 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  * is passed to [
13610 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
13620 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
13630 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
13640 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
13650 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
13660 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
13670 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
13680 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
13690 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67  the [total_chang
136a0 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
136b0 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
136c0 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
136d0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
136e0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
136f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
13700 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
13710 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
13720 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
13730 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
13740 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
13750 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
13760 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
13770 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
13780 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
13790 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
137a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
137b0 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
137c0 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
137d0 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
137e0 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
137f0 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
13800 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
13810 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
13820 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
13830 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
13840 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
13850 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
13860 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
13870 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
13880 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
13890 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
138a0 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
138b0 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
138c0 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
138d0 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
138e0 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
138f0 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
13900 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
13910 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
13920 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
13930 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
13940 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
13950 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
13960 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
13970 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
13980 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
13990 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
139a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
139b0 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
139c0 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
139d0 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
139e0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
139f0 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
13a00 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
13a10 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
13a20 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
13a30 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
13a40 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
13a50 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
13a60 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
13a70 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
13a80 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
13a90 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
13aa0 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
13ab0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
13ac0 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
13ad0 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
13ae0 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
13af0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
13b00 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
13b10 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
13b20 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
13b30 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
13b40 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
13b50 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
13b60 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
13b70 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
13b80 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
13b90 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
13ba0 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
13bb0 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
13bc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
13bd0 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
13be0 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
13bf0 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
13c00 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
13c10 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
13c20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13c30 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
13c40 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
13c50 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
13c60 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
13c70 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
13c80 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
13c90 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
13ca0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
13cb0 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
13cc0 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
13cd0 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
13ce0 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
13cf0 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
13d00 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
13d10 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
13d20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
13d30 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
13d40 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
13d50 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
13d60 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
13d70 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
13d80 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
13d90 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
13da0 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
13db0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
13dc0 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
13dd0 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
13de0 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
13df0 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
13e00 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
13e10 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
13e20 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
13e30 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
13e40 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
13e50 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
13e60 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
13e70 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
13e80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
13e90 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
13ea0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
13eb0 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
13ec0 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
13ed0 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
13ee0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
13ef0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
13f00 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
13f10 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13f20 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
13f30 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
13f40 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
13f50 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
13f60 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
13f70 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
13f80 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
13f90 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
13fa0 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
13fb0 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
13fc0 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
13fd0 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
13fe0 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
13ff0 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
14000 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
14010 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
14020 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
14030 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
14040 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
14050 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
14060 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
14070 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
14080 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
14090 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
140a0 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
140b0 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
140c0 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
140d0 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
140e0 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
140f0 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
14100 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
14110 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
14120 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
14130 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
14140 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
14150 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
14160 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
14170 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
14180 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
14190 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
141a0 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
141b0 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
141c0 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
141d0 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
141e0 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
141f0 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
14200 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
14210 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
14220 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
14230 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
14240 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
14250 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
14260 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
14270 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
14280 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
14290 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
142a0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
142b0 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
142c0 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
142d0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
142e0 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
142f0 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
14300 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
14310 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
14320 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
14330 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
14340 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
14350 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
14360 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
14370 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
14380 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
14390 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
143a0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
143b0 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
143c0 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
143d0 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
143e0 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
143f0 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
14400 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
14410 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
14420 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
14430 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
14440 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
14450 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
14460 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
14470 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
14480 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
14490 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
144a0 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
144b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
144c0 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
144d0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
144e0 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
144f0 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
14500 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
14510 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
14520 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
14530 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
14540 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
14550 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51  yte order..*/.SQ
14560 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
14570 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
14580 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
14590 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
145a0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
145b0 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
145c0 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
145d0 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
145e0 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
145f0 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
14600 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
14610 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
14620 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
14630 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
14640 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
14650 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
14660 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
14670 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
14680 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
14690 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
146a0 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
146b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
146c0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
146d0 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
146e0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
146f0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
14700 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
14710 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
14720 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
14730 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
14740 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
14750 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
14760 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
14770 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
14780 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
14790 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
147a0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
147b0 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
147c0 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
147d0 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
147e0 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
147f0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
14800 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
14810 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
14820 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14830 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
14840 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
14850 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
14860 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
14870 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
14880 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
14890 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
148a0 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
148b0 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
148c0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
148d0 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
148e0 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
148f0 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
14900 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
14910 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
14920 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
14930 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
14940 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
14950 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
14960 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
14970 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
14980 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
14990 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
149a0 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
149b0 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
149c0 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
149d0 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
149e0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
149f0 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
14a00 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
14a10 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
14a20 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
14a30 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
14a40 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
14a50 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
14a60 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
14a70 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
14a80 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
14a90 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
14aa0 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
14ab0 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
14ac0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
14ad0 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
14ae0 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
14af0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
14b00 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
14b10 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
14b20 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
14b30 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
14b40 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
14b50 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
14b60 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
14b70 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
14b80 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
14b90 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
14ba0 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
14bb0 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
14bc0 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
14bd0 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
14be0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
14bf0 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
14c00 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
14c10 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
14c20 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
14c30 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
14c40 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
14c50 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
14c60 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
14c70 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
14c80 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
14c90 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
14ca0 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
14cb0 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
14cc0 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
14cd0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
14ce0 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
14cf0 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
14d00 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
14d10 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
14d20 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
14d30 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
14d40 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
14d50 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
14d60 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
14d70 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
14d80 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
14d90 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
14da0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
14db0 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
14dc0 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
14dd0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
14de0 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
14df0 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
14e00 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
14e10 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
14e20 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
14e30 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
14e40 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
14e50 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
14e60 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
14e70 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
14e80 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
14e90 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
14ea0 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
14eb0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
14ec0 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
14ed0 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
14ee0 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
14ef0 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
14f00 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
14f10 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
14f20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
14f30 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
14f40 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
14f50 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
14f60 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
14f70 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
14f80 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
14f90 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
14fa0 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
14fb0 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
14fc0 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
14fd0 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
14fe0 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
14ff0 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
15000 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
15010 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
15020 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
15030 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
15040 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
15050 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
15060 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
15070 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
15080 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
15090 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
150a0 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
150b0 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
150c0 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
150d0 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
150e0 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
150f0 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
15100 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
15110 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
15120 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
15130 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
15140 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
15150 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
15160 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
15170 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
15180 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
15190 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
151a0 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
151b0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
151c0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
151d0 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
151e0 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
151f0 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
15200 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
15210 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
15220 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
15230 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
15240 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
15250 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
15260 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
15270 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
15280 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
15290 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
152a0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
152b0 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
152c0 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
152d0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
152e0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
152f0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
15300 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
15310 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
15320 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
15330 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
15340 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
15350 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
15360 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
15370 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
15380 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
15390 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
153a0 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
153b0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
153c0 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
153d0 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
153e0 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
153f0 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
15400 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
15410 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
15420 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
15430 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
15440 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
15450 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
15460 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
15470 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
15480 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
15490 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
154a0 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
154b0 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
154c0 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
154d0 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
154e0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
154f0 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
15500 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
15510 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
15520 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
15530 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
15540 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
15550 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
15560 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
15570 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
15580 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
15590 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
155a0 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
155b0 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
155c0 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
155d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
155e0 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
155f0 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
15600 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
15610 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
15620 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
15630 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
15640 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
15650 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
15660 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
15670 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
15680 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
15690 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
156a0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
156b0 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
156c0 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
156d0 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
156e0 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
156f0 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
15700 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
15710 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
15720 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
15730 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
15740 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
15750 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
15760 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
15770 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
15780 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
15790 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
157a0 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
157b0 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
157c0 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
157d0 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
157e0 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
157f0 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
15800 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
15810 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
15820 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
15830 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
15840 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
15850 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
15860 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
15870 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
15880 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
15890 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
158a0 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
158b0 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
158c0 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
158d0 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
158e0 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
158f0 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
15900 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
15910 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
15920 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
15930 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
15940 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
15950 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
15960 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
15970 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
15980 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
15990 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
159a0 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
159b0 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
159c0 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
159d0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
159e0 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
159f0 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
15a00 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
15a10 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
15a20 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
15a30 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
15a40 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
15a50 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
15a60 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
15a70 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
15a80 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
15a90 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
15aa0 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
15ab0 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
15ac0 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
15ad0 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
15ae0 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
15af0 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
15b00 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
15b10 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
15b20 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
15b30 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
15b40 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
15b50 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
15b60 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
15b70 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
15b80 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
15b90 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
15ba0 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
15bb0 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
15bc0 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
15bd0 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
15be0 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
15bf0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
15c00 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
15c10 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
15c20 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
15c30 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
15c40 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
15c50 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
15c60 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
15c70 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
15c80 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
15c90 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
15ca0 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
15cb0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
15cc0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
15cd0 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
15ce0 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
15cf0 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
15d00 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
15d10 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
15d20 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
15d30 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
15d40 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
15d50 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
15d60 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
15d70 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
15d80 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
15d90 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
15da0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
15db0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
15dc0 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
15dd0 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
15de0 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
15df0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
15e00 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
15e10 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
15e20 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
15e30 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
15e40 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
15e50 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
15e60 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
15e70 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
15e80 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
15e90 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
15ea0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
15eb0 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
15ec0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
15ed0 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
15ee0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
15ef0 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
15f00 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
15f10 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
15f20 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
15f30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
15f40 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
15f50 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
15f60 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
15f70 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
15f80 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
15f90 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
15fa0 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
15fb0 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
15fc0 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
15fd0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
15fe0 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
15ff0 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
16000 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
16010 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
16020 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
16030 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
16040 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
16050 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
16060 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
16070 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
16080 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
16090 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
160a0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
160b0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
160c0 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
160d0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
160e0 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
160f0 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
16100 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
16110 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
16120 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
16130 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
16140 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
16150 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
16160 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
16170 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
16180 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
16190 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
161a0 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
161b0 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
161c0 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
161d0 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
161e0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
161f0 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
16200 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
16210 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
16220 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
16230 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
16240 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
16250 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
16260 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
16270 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
16280 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
16290 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
162a0 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
162b0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
162c0 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
162d0 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
162e0 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
162f0 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
16300 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
16310 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
16320 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
16330 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  sg()]..*/.SQLITE
16340 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
16350 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
16360 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
16370 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
16380 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
16390 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
163a0 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
163b0 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
163c0 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
163d0 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
163e0 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
163f0 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
16400 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
16410 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
16420 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
16430 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
16440 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
16450 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
16460 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
16470 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
16480 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
16490 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
164a0 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c  n here */.);.SQL
164b0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
164c0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
164d0 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
164e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
164f0 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
16500 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
16510 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
16520 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
16530 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
16540 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
16550 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
16560 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
16570 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
16580 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
16590 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
165a0 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
165b0 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
165c0 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
165d0 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
165e0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
165f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
16600 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
16610 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
16620 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
16630 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
16640 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
16650 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
16660 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
16670 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
16680 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
16690 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
166a0 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
166b0 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
166c0 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
166d0 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
166e0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
166f0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
16700 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
16710 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
16720 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
16730 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
16740 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
16750 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
16760 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
16770 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
16780 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
16790 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
167a0 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
167b0 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
167c0 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
167d0 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
167e0 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
167f0 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
16800 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
16810 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
16820 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
16830 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
16840 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
16850 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
16860 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
16870 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
16880 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
16890 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
168a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
168b0 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
168c0 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
168d0 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
168e0 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
168f0 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
16900 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
16910 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
16920 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
16930 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
16940 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
16950 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
16960 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
16970 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
16980 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
16990 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
169a0 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
169b0 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
169c0 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
169d0 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
169e0 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
169f0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
16a00 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
16a10 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
16a20 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
16a30 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
16a40 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
16a50 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
16a60 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
16a70 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
16a80 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
16a90 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
16aa0 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
16ab0 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
16ac0 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
16ad0 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
16ae0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
16af0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
16b00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
16b10 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
16b20 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
16b30 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
16b40 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
16b50 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
16b60 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
16b70 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
16b80 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
16b90 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
16ba0 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
16bb0 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
16bc0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
16bd0 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
16be0 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
16bf0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
16c00 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
16c10 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
16c20 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
16c30 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
16c40 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
16c50 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
16c60 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
16c70 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
16c80 6e 75 6c 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a  null-terminated.
16c90 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74  ** string from t
16ca0 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74  he argument list
16cb0 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64  .  But %q also d
16cc0 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27  oubles every '\'
16cd0 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  ' character..** 
16ce0 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66  %q is designed f
16cf0 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20  or use inside a 
16d00 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29  string literal.)
16d10 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65  ^  By doubling e
16d20 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72  ach '\''.** char
16d30 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73  acter it escapes
16d40 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20   that character 
16d50 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f  and allows it to
16d60 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74   be inserted int
16d70 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e  o.** the string.
16d80 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70  .**.** For examp
16d90 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73  le, assume the s
16da0 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a  tring variable z
16db0 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65  Text contains te
16dc0 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  xt as follows:.*
16dd0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
16de0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
16df0 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61  *zText = "It's a
16e00 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a   happy day!";.**
16e10 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
16e20 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63  ote>.**.** One c
16e30 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74  an use this text
16e40 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
16e50 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  ment as follows:
16e60 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
16e70 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
16e80 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
16e90 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
16ea0 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
16eb0 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78  UES('%q')", zTex
16ec0 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
16ed0 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
16ee0 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
16ef0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
16f00 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
16f10 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65  kquote>.**.** Be
16f20 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72  cause the %q for
16f30 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73  mat string is us
16f40 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61  ed, the '\'' cha
16f50 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a  racter in zText.
16f60 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e  ** is escaped an
16f70 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61  d the SQL genera
16f80 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77  ted is as follow
16f90 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
16fa0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
16fb0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
16fc0 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20  1 VALUES('It''s 
16fd0 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a  a happy day!').*
16fe0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
16ff0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
17000 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61   is correct.  Ha
17010 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73  d we used %s ins
17020 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20  tead of %q, the 
17030 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a  generated SQL.**
17040 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b   would have look
17050 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a  ed like this:.**
17060 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
17070 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
17080 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
17090 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70  UES('It's a happ
170a0 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70  y day!');.** </p
170b0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
170c0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f  .**.** This seco
170d0 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e  nd example is an
170e0 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f   SQL syntax erro
170f0 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c  r.  As a general
17100 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64   rule you should
17110 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25  .** always use %
17120 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20  q instead of %s 
17130 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74  when inserting t
17140 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e  ext into a strin
17150 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a  g literal..**.**
17160 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e   ^(The %Q option
17170 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65   works like %q e
17180 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64  xcept it also ad
17190 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ds single quotes
171a0 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f   around.** the o
171b0 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f  utside of the to
171c0 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64  tal string.  Add
171d0 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68  itionally, if th
171e0 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74  e parameter in t
171f0 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c  he.** argument l
17200 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ist is a NULL po
17210 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69  inter, %Q substi
17220 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22  tutes the text "
17230 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a  NULL" (without.*
17240 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29  * single quotes)
17250 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61  .)^  So, for exa
17260 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20  mple, one could 
17270 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  say:.**.** <bloc
17280 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
17290 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
172a0 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
172b0 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
172c0 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54   VALUES(%Q)", zT
172d0 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  ext);.**  sqlite
172e0 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c  3_exec(db, zSQL,
172f0 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73   0, 0, 0);.**  s
17300 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c  qlite3_free(zSQL
17310 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
17320 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
17330 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77  The code above w
17340 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72  ill render a cor
17350 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65  rect SQL stateme
17360 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a  nt in the zSQL.*
17370 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20  * variable even 
17380 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72  if the zText var
17390 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20  iable is a NULL 
173a0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
173b0 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74  (The "%z" format
173c0 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  ting option work
173d0 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20  s like "%s" but 
173e0 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69  with the.** addi
173f0 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20  tion that after 
17400 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62  the string has b
17410 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70  een read and cop
17420 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ied into.** the 
17430 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33  result, [sqlite3
17440 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c  _free()] is call
17450 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20  ed on the input 
17460 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c  string.)^.*/.SQL
17470 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
17480 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f  lite3_mprintf(co
17490 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a  nst char*,...);.
174a0 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
174b0 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74  *sqlite3_vmprint
174c0 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76  f(const char*, v
174d0 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f  a_list);.SQLITE_
174e0 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
174f0 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  3_snprintf(int,c
17500 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
17510 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41  , ...);.SQLITE_A
17520 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
17530 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
17540 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
17550 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
17560 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
17570 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
17580 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
17590 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
175a0 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
175b0 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
175c0 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
175d0 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
175e0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
175f0 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
17600 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
17610 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
17620 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
17630 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
17640 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
17650 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
17660 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
17670 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
17680 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
17690 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
176a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
176b0 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
176c0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
176d0 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
176e0 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
176f0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
17700 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
17710 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
17720 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
17730 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
17740 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
17750 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
17760 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
17770 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
17780 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
17790 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
177a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
177b0 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
177c0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
177d0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
177e0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
177f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
17800 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
17810 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
17820 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
17830 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
17840 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
17850 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
17860 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
17870 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
17880 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
17890 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
178a0 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
178b0 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
178c0 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
178d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
178e0 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
178f0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
17900 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
17910 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
17920 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
17930 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
17940 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
17950 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
17960 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
17970 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
17980 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
17990 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
179a0 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
179b0 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
179c0 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
179d0 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
179e0 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
179f0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
17a00 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
17a10 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
17a20 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
17a30 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
17a40 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
17a50 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
17a60 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
17a70 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
17a80 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
17a90 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
17aa0 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
17ab0 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
17ac0 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
17ad0 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
17ae0 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
17af0 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
17b00 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
17b10 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
17b20 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
17b30 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
17b40 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
17b50 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
17b60 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
17b70 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
17b80 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17b90 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
17ba0 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
17bb0 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
17bc0 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
17bd0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
17be0 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
17bf0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
17c00 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
17c10 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
17c20 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
17c30 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
17c40 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
17c50 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
17c60 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
17c70 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
17c80 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
17c90 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
17ca0 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
17cb0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
17cc0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
17cd0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
17ce0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
17cf0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
17d00 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
17d10 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
17d20 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
17d30 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
17d40 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
17d50 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
17d60 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
17d70 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
17d80 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
17d90 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
17da0 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
17db0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
17dc0 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
17dd0 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
17de0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
17df0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
17e00 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
17e10 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
17e20 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
17e30 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
17e40 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
17e50 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
17e60 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
17e70 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
17e80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
17e90 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
17ea0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
17eb0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
17ec0 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
17ed0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
17ee0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
17ef0 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
17f00 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
17f10 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
17f20 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
17f30 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
17f40 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
17f50 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
17f60 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
17f70 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
17f80 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
17f90 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
17fa0 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
17fb0 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
17fc0 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
17fd0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
17fe0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
17ff0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
18000 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
18010 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
18020 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
18030 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
18040 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
18050 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
18060 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
18070 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77  **.** The Window
18080 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
18090 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68  ayer calls.** th
180a0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
180b0 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
180c0 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
180d0 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
180e0 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
180f0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
18100 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
18110 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
18120 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
18130 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
18140 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
18150 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
18160 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
18170 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20  tion errors are 
18180 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
18190 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74   they are report
181a0 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
181b0 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
181c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
181d0 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
181e0 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
181f0 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
18200 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
18210 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
18220 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
18230 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
18240 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
18250 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
18260 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
18270 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
18280 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
18290 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
182a0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
182b0 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
182c0 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
182d0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
182e0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
182f0 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
18300 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
18310 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
18320 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
18330 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
18340 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
18350 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
18360 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
18370 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
18380 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   *sqlite3_malloc
18390 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  (int);.SQLITE_AP
183a0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
183b0 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
183c0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
183d0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
183e0 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  e(void*);../*.**
183f0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
18400 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74  y Allocator Stat
18410 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c  istics.**.** SQL
18420 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65  ite provides the
18430 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65  se two interface
18440 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20  s for reporting 
18450 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a  on the status.**
18460 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
18470 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c  _malloc()], [sql
18480 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e  ite3_free()], an
18490 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
184a0 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65  oc()].** routine
184b0 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68  s, which form th
184c0 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72  e built-in memor
184d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62  y allocation sub
184e0 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  system..**.** ^T
184f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
18500 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69  ry_used()] routi
18510 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
18520 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a  umber of bytes.*
18530 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72  * of memory curr
18540 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e  ently outstandin
18550 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20  g (malloced but 
18560 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e  not freed)..** ^
18570 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
18580 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
18590 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
185a0 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20   the maximum.** 
185b0 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65  value of [sqlite
185c0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
185d0 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d   since the high-
185e0 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61  water mark.** wa
185f0 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e  s last reset.  ^
18600 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  The values retur
18610 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
18620 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61  memory_used()] a
18630 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  nd.** [sqlite3_m
18640 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
18650 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f  )] include any o
18660 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64  verhead.** added
18670 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74   by SQLite in it
18680 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  s implementation
18690 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
186a0 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e  loc()],.** but n
186b0 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65  ot overhead adde
186c0 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64  d by the any und
186d0 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c  erlying system l
186e0 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e  ibrary.** routin
186f0 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  es that [sqlite3
18700 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63  _malloc()] may c
18710 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  all..**.** ^The 
18720 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65  memory high-wate
18730 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20  r mark is reset 
18740 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76  to the current v
18750 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69  alue of.** [sqli
18760 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
18770 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  )] if and only i
18780 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
18790 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  to.** [sqlite3_m
187a0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
187b0 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68  )] is true.  ^Th
187c0 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
187d0 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  .** by [sqlite3_
187e0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
187f0 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68  (1)] is the high
18800 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70  -water mark.** p
18810 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65  rior to the rese
18820 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
18830 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
18840 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
18850 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ed(void);.SQLITE
18860 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
18870 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
18880 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20  y_highwater(int 
18890 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a  resetFlag);../*.
188a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65  ** CAPI3REF: Pse
188b0 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65  udo-Random Numbe
188c0 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a  r Generator.**.*
188d0 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e  * SQLite contain
188e0 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79  s a high-quality
188f0 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e   pseudo-random n
18900 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20  umber generator 
18910 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a  (PRNG) used to.*
18920 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20  * select random 
18930 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d  [ROWID | ROWIDs]
18940 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
18950 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f  new records into
18960 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a   a table that.**
18970 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68   already uses th
18980 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62  e largest possib
18990 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65  le [ROWID].  The
189a0 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73   PRNG is also us
189b0 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75  ed for.** the bu
189c0 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20  ild-in random() 
189d0 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29  and randomblob()
189e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20   SQL functions. 
189f0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
18a00 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63  allows.** applic
18a10 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73  ations to access
18a20 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66   the same PRNG f
18a30 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65  or other purpose
18a40 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c  s..**.** ^A call
18a50 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65   to this routine
18a60 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20   stores N bytes 
18a70 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  of randomness in
18a80 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a  to buffer P..**.
18a90 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
18aa0 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  me this routine 
18ab0 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68  is invoked (eith
18ac0 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72  er internally or
18ad0 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   by.** the appli
18ae0 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47  cation) the PRNG
18af0 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67   is seeded using
18b00 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
18b10 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ined.** from the
18b20 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74   xRandomness met
18b30 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
18b40 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
18b50 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20   object..** ^On 
18b60 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69  all subsequent i
18b70 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20  nvocations, the 
18b80 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73  pseudo-randomnes
18b90 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a  s is generated.*
18ba0 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64  * internally and
18bb0 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73   without recours
18bc0 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  e to the [sqlite
18bd0 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65  3_vfs] xRandomne
18be0 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f  ss.** method..*/
18bf0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
18c00 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
18c10 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
18c20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
18c30 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
18c40 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
18c50 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
18c60 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
18c70 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
18c80 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
18c90 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
18ca0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
18cb0 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
18cc0 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
18cd0 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
18ce0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
18cf0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
18d00 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
18d10 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
18d20 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
18d30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
18d40 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
18d50 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
18d60 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
18d70 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
18d80 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
18d90 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
18da0 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
18db0 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
18dc0 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
18dd0 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
18de0 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
18df0 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
18e00 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
18e10 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
18e20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
18e30 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
18e40 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
18e50 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
18e60 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
18e70 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
18e80 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
18e90 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
18ea0 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
18eb0 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
18ec0 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
18ed0 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
18ee0 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
18ef0 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
18f00 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
18f10 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
18f20 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
18f30 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
18f40 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
18f50 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
18f60 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
18f70 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
18f80 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
18f90 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
18fa0 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
18fb0 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
18fc0 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
18fd0 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
18fe0 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
18ff0 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
19000 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
19010 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
19020 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
19030 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
19040 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
19050 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
19060 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
19070 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
19080 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
19090 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
190a0 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
190b0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
190c0 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
190d0 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
190e0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
190f0 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
19100 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
19110 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
19120 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
19130 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
19140 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
19150 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
19160 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
19170 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
19180 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
19190 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
191a0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
191b0 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
191c0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
191d0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
191e0 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
191f0 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
19200 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
19210 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
19220 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
19230 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
19240 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
19250 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
19260 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
19270 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
19280 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
19290 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
192a0 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
192b0 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
192c0 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
192d0 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
192e0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
192f0 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
19300 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
19310 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
19320 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
19330 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
19340 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
19350 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
19360 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
19370 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
19380 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
19390 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
193a0 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
193b0 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
193c0 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
193d0 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
193e0 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
193f0 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
19400 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
19410 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
19420 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
19430 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
19440 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
19450 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
19460 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
19470 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
19480 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
19490 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
194a0 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
194b0 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
194c0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
194d0 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
194e0 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
194f0 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
19500 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
19510 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
19520 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
19530 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
19540 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
19550 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
19560 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
19570 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
19580 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
19590 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
195a0 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
195b0 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
195c0 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
195d0 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
195e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
195f0 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
19600 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
19610 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
19620 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
19630 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
19640 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
19650 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
19660 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
19670 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
19680 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
19690 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
196a0 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
196b0 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
196c0 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
196d0 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
196e0 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
196f0 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
19700 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
19710 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
19720 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
19730 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
19740 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
19750 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
19760 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
19770 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
19780 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
19790 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
197a0 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
197b0 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
197c0 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
197d0 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
197e0 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
197f0 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
19800 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
19810 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
19820 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
19830 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
19840 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
19850 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
19860 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
19870 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
19880 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
19890 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
198a0 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
198b0 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
198c0 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
198d0 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
198e0 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
198f0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
19900 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
19910 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
19920 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
19930 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
19940 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
19950 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
19960 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
19970 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
19980 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
19990 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
199a0 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
199b0 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
199c0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
199d0 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
199e0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
199f0 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
19a00 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
19a10 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
19a20 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
19a30 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
19a40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19a50 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
19a60 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
19a70 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
19a80 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
19a90 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
19aa0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
19ab0 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
19ac0 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
19ad0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
19ae0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
19af0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
19b00 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
19b10 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
19b20 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
19b30 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
19b40 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
19b50 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
19b60 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
19b70 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
19b80 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
19b90 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
19ba0 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
19bb0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19bc0 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
19bd0 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
19be0 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
19bf0 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
19c00 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
19c10 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
19c20 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
19c30 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
19c40 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
19c50 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
19c60 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
19c70 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
19c80 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
19c90 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
19ca0 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
19cb0 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
19cc0 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
19cd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
19ce0 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
19cf0 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
19d00 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
19d10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
19d20 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
19d30 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
19d40 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
19d50 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
19d60 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
19d70 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
19d80 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
19d90 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65  orizer(.  sqlite
19da0 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74  3*,.  int (*xAut
19db0 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  h)(void*,int,con
19dc0 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
19dd0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
19de0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20  ,const char*),. 
19df0 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61   void *pUserData
19e00 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
19e10 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
19e20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Return Codes.**.
19e30 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
19e40 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
19e50 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
19e60 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d  back function] m
19e70 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69  ust.** return ei
19e80 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  ther [SQLITE_OK]
19e90 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65   or one of these
19ea0 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69   two constants i
19eb0 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69  n order.** to si
19ec0 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74  gnal SQLite whet
19ed0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61  her or not the a
19ee0 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
19ef0 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  ed.  See the.** 
19f00 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
19f10 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
19f20 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69  izer documentati
19f30 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  on] for addition
19f40 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
19f50 6e 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  n..*/.#define SQ
19f60 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
19f70 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
19f80 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
19f90 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
19fa0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
19fb0 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
19fc0 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
19fd0 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
19fe0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
19ff0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1a000 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
1a010 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1a020 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1a030 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1a040 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1a050 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1a060 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1a070 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1a080 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1a090 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1a0a0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1a0b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1a0c0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1a0d0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1a0e0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1a0f0 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1a100 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1a110 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1a120 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1a130 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1a140 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1a150 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1a160 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1a170 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1a180 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1a190 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1a1a0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1a1b0 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1a1c0 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1a1d0 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1a1e0 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1a1f0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1a200 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1a210 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1a220 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1a230 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1a240 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1a250 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1a260 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
1a270 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
1a280 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1a290 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
1a2a0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
1a2b0 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
1a2c0 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
1a2d0 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
1a2e0 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
1a2f0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1a300 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
1a310 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
1a320 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
1a330 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
1a340 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1a350 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
1a360 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
1a370 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
1a380 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
1a390 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
1a3a0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
1a3b0 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1a3c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a3d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
1a3e0 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
1a3f0 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
1a400 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a410 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
1a420 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
1a430 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1a440 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1a450 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1a460 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
1a470 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
1a480 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1a490 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1a4a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1a4b0 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
1a4c0 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
1a4d0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1a4e0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1a4f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1a500 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
1a510 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
1a520 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1a530 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1a540 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1a550 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
1a560 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
1a570 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1a580 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1a590 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1a5a0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
1a5b0 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
1a5c0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1a5d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1a5e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1a5f0 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1a600 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
1a610 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1a620 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1a630 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1a640 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
1a650 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1a660 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1a670 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1a680 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
1a690 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
1a6a0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1a6b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1a6c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1a6d0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
1a6e0 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
1a6f0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1a700 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1a710 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1a720 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
1a730 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
1a740 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1a750 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1a760 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a770 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
1a780 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
1a790 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1a7a0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1a7b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a7c0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
1a7d0 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
1a7e0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1a7f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1a800 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a810 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
1a820 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
1a830 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1a840 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1a850 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a860 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
1a870 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
1a880 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1a890 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1a8a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a8b0 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
1a8c0 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
1a8d0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1a8e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1a8f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a900 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
1a910 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
1a920 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1a930 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1a940 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1a950 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
1a960 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
1a970 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1a980 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1a990 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
1a9a0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
1a9b0 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
1a9c0 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
1a9d0 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
1a9e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
1a9f0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1aa00 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
1aa10 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1aa20 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1aa30 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
1aa40 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
1aa50 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
1aa60 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1aa70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1aa80 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
1aa90 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
1aaa0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
1aab0 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
1aac0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1aad0 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
1aae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1aaf0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1ab00 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1ab10 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1ab20 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
1ab30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
1ab40 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
1ab50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ab60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ab70 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
1ab80 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
1ab90 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1aba0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
1abb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1abc0 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
1abd0 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
1abe0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1abf0 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
1ac00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ac10 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
1ac20 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
1ac30 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1ac40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ac50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ac60 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
1ac70 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
1ac80 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1ac90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1aca0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1acb0 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
1acc0 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
1acd0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ace0 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1acf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ad00 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
1ad10 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
1ad20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ad30 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1ad40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ad50 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
1ad60 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
1ad70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
1ad80 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
1ad90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ada0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
1adb0 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
1adc0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
1add0 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
1ade0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1adf0 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
1ae00 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
1ae10 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
1ae20 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ae30 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
1ae40 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
1ae50 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1ae60 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
1ae70 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
1ae80 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
1ae90 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
1aea0 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
1aeb0 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
1aec0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
1aed0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
1aee0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
1aef0 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
1af00 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
1af10 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
1af20 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
1af30 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1af40 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
1af50 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1af60 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
1af70 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1af80 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
1af90 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
1afa0 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
1afb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
1afc0 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
1afd0 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
1afe0 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
1aff0 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
1b000 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
1b010 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
1b020 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
1b030 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
1b040 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
1b050 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
1b060 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
1b070 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
1b080 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
1b090 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
1b0a0 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ger.)^.**.** ^Th
1b0b0 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1b0c0 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1b0d0 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
1b0e0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1b0f0 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
1b100 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
1b110 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1b120 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
1b130 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
1b140 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
1b150 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
1b160 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
1b170 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
1b180 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
1b190 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
1b1a0 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1b1b0 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
1b1c0 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
1b1d0 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
1b1e0 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
1b1f0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
1b200 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
1b210 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
1b220 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
1b230 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
1b240 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
1b250 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
1b260 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
1b270 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1b280 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
1b290 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
1b2a0 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
1b2b0 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
1b2c0 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
1b2d0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1b2e0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
1b2f0 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
1b300 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
1b310 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
1b320 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
1b330 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
1b340 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1b350 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
1b360 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
1b370 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
1b380 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
1b390 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  d*);.SQLITE_API 
1b3a0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
1b3b0 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
1b3c0 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
1b3d0 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
1b3e0 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
1b3f0 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
1b400 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
1b410 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b420 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
1b430 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  s Callbacks.**.*
1b440 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
1b450 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1b460 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
1b470 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
1b480 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
1b490 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
1b4a0 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
1b4b0 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
1b4c0 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
1b4d0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1b4e0 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1b4f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1b500 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
1b510 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1b520 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
1b530 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
1b540 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
1b550 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
1b560 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
1b570 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
1b580 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
1b590 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
1b5a0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
1b5b0 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
1b5c0 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
1b5d0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
1b5e0 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
1b5f0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
1b600 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
1b610 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
1b620 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
1b630 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
1b640 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
1b650 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
1b660 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a   callback X..**.
1b670 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
1b680 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1b690 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
1b6a0 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
1b6b0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1b6c0 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
1b6d0 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
1b6e0 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
1b6f0 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
1b700 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
1b710 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
1b720 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
1b730 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
1b740 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
1b750 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
1b760 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
1b770 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
1b780 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
1b790 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1b7a0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
1b7b0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1b7c0 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
1b7d0 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
1b7e0 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
1b7f0 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
1b800 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
1b810 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
1b820 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
1b830 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
1b840 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
1b850 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
1b860 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
1b870 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
1b880 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
1b890 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1b8a0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
1b8b0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1b8c0 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
1b8d0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1b8e0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1b8f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1b900 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1b910 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1b920 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1b930 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1b940 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1b950 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53  ragraph..**.*/.S
1b960 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1b970 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
1b980 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1b990 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
1b9a0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
1b9b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
1b9c0 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
1b9d0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
1b9e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1b9f0 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
1ba00 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
1ba10 69 6c 65 20 77 68 6f 73 65 20 6e 61 6d 65 20 69  ile whose name i
1ba20 73 20 67 69 76 65 6e 20 62 79 20 74 68 65 0a 2a  s given by the.*
1ba30 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
1ba40 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
1ba50 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
1ba60 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
1ba70 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
1ba80 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1ba90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1baa0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
1bab0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1bac0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
1bad0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
1bae0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
1baf0 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
1bb00 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
1bb10 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
1bb20 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
1bb30 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
1bb40 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
1bb50 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
1bb60 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
1bb70 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1bb80 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
1bb90 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
1bba0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
1bbb0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
1bbc0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
1bbd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1bbe0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
1bbf0 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
1bc00 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1bc10 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
1bc20 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
1bc30 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
1bc40 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
1bc50 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
1bc60 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
1bc70 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
1bc80 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
1bc90 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
1bca0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
1bcb0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
1bcc0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
1bcd0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
1bce0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
1bcf0 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
1bd00 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
1bd10 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
1bd20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
1bd30 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
1bd40 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1bd50 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
1bd60 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1bd70 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
1bd80 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1bd90 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1bda0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
1bdb0 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
1bdc0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1bdd0 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
1bde0 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
1bdf0 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
1be00 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
1be10 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
1be20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
1be30 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
1be40 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
1be50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1be60 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
1be70 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
1be80 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
1be90 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
1bea0 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
1beb0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
1bec0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1bed0 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
1bee0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
1bef0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
1bf00 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1bf10 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
1bf20 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
1bf30 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
1bf40 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
1bf50 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1bf60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1bf70 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
1bf80 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
1bf90 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
1bfa0 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
1bfb0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
1bfc0 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
1bfd0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
1bfe0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
1bff0 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1c000 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1c010 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
1c020 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1c030 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  CACHE],.** and/o
1c040 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  r [SQLITE_OPEN_P
1c050 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
1c060 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
1c070 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1c080 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
1c090 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c0a0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1c0b0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
1c0c0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
1c0d0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1c0e0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
1c0f0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
1c100 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
1c110 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
1c120 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1c130 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1c140 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1c150 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1c160 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1c170 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
1c180 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
1c190 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
1c1a0 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1c1b0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1c1c0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
1c1d0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
1c1e0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
1c1f0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
1c200 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
1c210 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1c220 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1c230 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1c240 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
1c250 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
1c260 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1c270 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1c280 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1c290 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
1c2a0 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
1c2b0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
1c2c0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
1c2d0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
1c2e0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
1c2f0 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
1c300 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1c310 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
1c320 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
1c330 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1c340 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1c350 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1c360 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1c370 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1c380 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f  shown above or o
1c390 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e  ne of the combin
1c3a0 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1c3b0 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77  ve combined.** w
1c3c0 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
1c3d0 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
1c3e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1c3f0 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  MUTEX],.** [SQLI
1c400 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1c410 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  CHE] and/or [SQL
1c420 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1c430 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a  CACHE] flags,.**
1c440 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1c450 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1c460 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
1c470 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1c480 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1c490 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1c4a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1c4b0 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
1c4c0 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
1c4d0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
1c4e0 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
1c4f0 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
1c500 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
1c510 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1c520 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1c530 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
1c540 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1c550 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1c560 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
1c570 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
1c580 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
1c590 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1c5a0 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
1c5b0 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
1c5c0 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
1c5d0 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
1c5e0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1c5f0 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
1c600 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
1c610 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
1c620 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
1c630 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1c640 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
1c650 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
1c660 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
1c670 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1c680 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
1c690 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
1c6a0 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
1c6b0 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
1c6c0 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
1c6d0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1c6e0 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1c6f0 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1c700 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c710 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
1c720 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
1c730 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1c740 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
1c750 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
1c760 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  If the filename 
1c770 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74  is ":memory:", t
1c780 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74  hen a private, t
1c790 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f  emporary in-memo
1c7a0 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  ry database.** i
1c7b0 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68  s created for th
1c7c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1c7d0 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64  This in-memory d
1c7e0 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e  atabase will van
1c7f0 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  ish when.** the 
1c800 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c810 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20  ion is closed.  
1c820 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1c830 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a  of SQLite might.
1c840 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61  ** make use of a
1c850 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61  dditional specia
1c860 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74  l filenames that
1c870 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20   begin with the 
1c880 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ":" character..*
1c890 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * It is recommen
1c8a0 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20  ded that when a 
1c8b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
1c8c0 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20  e actually does 
1c8d0 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20  begin with.** a 
1c8e0 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f  ":" character yo
1c8f0 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20  u should prefix 
1c900 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74  the filename wit
1c910 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63  h a pathname suc
1c920 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20  h as.** "./" to 
1c930 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e  avoid ambiguity.
1c940 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .**.** ^If the f
1c950 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d  ilename is an em
1c960 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  pty string, then
1c970 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70   a private, temp
1c980 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b  orary.** on-disk
1c990 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1c9a0 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69  e created.  ^Thi
1c9b0 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61  s private databa
1c9c0 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75  se will be.** au
1c9d0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
1c9e0 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74  ted as soon as t
1c9f0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1ca00 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
1ca10 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
1ca20 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1ca30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1ca40 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
1ca50 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
1ca60 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
1ca70 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
1ca80 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
1ca90 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
1caa0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
1cab0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
1cac0 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
1cad0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1cae0 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
1caf0 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
1cb00 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1cb10 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
1cb20 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  s used..**.** <b
1cb30 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
1cb40 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
1cb50 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
1cb60 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
1cb70 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
1cb80 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
1cb90 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
1cba0 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
1cbb0 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
1cbc0 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
1cbd0 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
1cbe0 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
1cbf0 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
1cc00 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
1cc10 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
1cc20 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
1cc30 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
1cc40 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
1cc50 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
1cc60 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1cc70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1cc80 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1cc90 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
1cca0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
1ccb0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
1ccc0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
1ccd0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
1cce0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
1ccf0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
1cd00 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
1cd10 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
1cd20 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
1cd30 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1cd40 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1cd50 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
1cd60 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
1cd70 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
1cd80 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
1cd90 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
1cda0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
1cdb0 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
1cdc0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1cdd0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1cde0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1cdf0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1ce00 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
1ce10 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1ce20 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
1ce30 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
1ce40 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
1ce50 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
1ce60 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
1ce70 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
1ce80 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
1ce90 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1cea0 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1ceb0 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
1cec0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1ced0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1cee0 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
1cef0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1cf00 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1cf10 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
1cf20 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
1cf30 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
1cf40 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
1cf50 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
1cf60 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cf70 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
1cf80 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
1cf90 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
1cfa0 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
1cfb0 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
1cfc0 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1cfd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
1cfe0 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
1cff0 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1d000 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1d010 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
1d020 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
1d030 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
1d040 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1d050 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1d060 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
1d070 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
1d080 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
1d090 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
1d0a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1d0b0 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1d0c0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1d0d0 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1d0e0 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1d0f0 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1d100 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1d110 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1d120 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1d130 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
1d140 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
1d150 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
1d160 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
1d170 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
1d180 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
1d190 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
1d1a0 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
1d1b0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
1d1c0 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
1d1d0 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
1d1e0 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
1d1f0 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
1d200 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1d210 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
1d220 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1d230 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68  ions.)^.**.** Wh
1d240 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
1d250 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1d260 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
1d270 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
1d280 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
1d290 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
1d2a0 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
1d2b0 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
1d2c0 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
1d2d0 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
1d2e0 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
1d2f0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
1d300 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
1d310 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
1d320 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
1d330 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
1d340 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
1d350 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
1d360 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1d370 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
1d380 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
1d390 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
1d3a0 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
1d3b0 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
1d3c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1d3d0 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
1d3e0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
1d3f0 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
1d400 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
1d410 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
1d420 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
1d430 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
1d440 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
1d450 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
1d460 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
1d470 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
1d480 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
1d490 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
1d4a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
1d4b0 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
1d4c0 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
1d4d0 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
1d4e0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
1d4f0 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
1d500 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
1d510 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
1d520 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
1d530 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
1d540 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
1d550 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
1d560 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1d570 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
1d580 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
1d590 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1d5a0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
1d5b0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
1d5c0 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
1d5d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
1d5e0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
1d5f0 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
1d600 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
1d610 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
1d620 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1d630 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
1d640 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
1d650 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
1d660 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1d670 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
1d680 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
1d690 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
1d6a0 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
1d6b0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
1d6c0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
1d6d0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
1d6e0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
1d6f0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
1d700 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
1d710 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
1d720 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
1d730 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
1d740 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
1d750 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
1d760 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
1d770 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
1d780 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
1d790 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
1d7a0 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
1d7b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1d7c0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
1d7d0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
1d7e0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
1d7f0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
1d800 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
1d810 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
1d820 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
1d830 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
1d840 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
1d850 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
1d860 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
1d870 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1d880 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
1d890 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
1d8a0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
1d8b0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
1d8c0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
1d8d0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
1d8e0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
1d8f0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
1d900 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1d910 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
1d920 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
1d930 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
1d940 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
1d950 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
1d960 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
1d970 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1d980 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
1d990 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1d9a0 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
1d9b0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
1d9c0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
1d9d0 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
1d9e0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1d9f0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
1da00 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
1da10 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
1da20 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
1da30 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
1da40 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
1da50 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
1da60 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
1da70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
1da80 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
1da90 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
1daa0 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
1dab0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1dac0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
1dad0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
1dae0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
1daf0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
1db00 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
1db10 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
1db20 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
1db30 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
1db40 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
1db50 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
1db60 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
1db70 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
1db80 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
1db90 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
1dba0 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
1dbb0 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
1dbc0 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
1dbd0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
1dbe0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
1dbf0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
1dc00 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1dc10 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
1dc20 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
1dc30 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
1dc40 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
1dc50 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
1dc60 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
1dc70 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
1dc80 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
1dc90 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
1dca0 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
1dcb0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
1dcc0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
1dcd0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
1dce0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
1dcf0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1dd00 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
1dd10 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1dd20 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
1dd30 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
1dd40 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
1dd50 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
1dd60 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
1dd70 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
1dd80 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
1dd90 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
1dda0 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
1ddb0 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
1ddc0 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
1ddd0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
1dde0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
1ddf0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
1de00 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
1de10 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
1de20 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
1de30 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
1de40 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1de50 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
1de60 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
1de70 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
1de80 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
1de90 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
1dea0 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
1deb0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
1dec0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
1ded0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
1dee0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
1def0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
1df00 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
1df10 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
1df20 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
1df30 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
1df40 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
1df50 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
1df60 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
1df70 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
1df80 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
1df90 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
1dfa0 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
1dfb0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
1dfc0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
1dfd0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
1dfe0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
1dff0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
1e000 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
1e010 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
1e020 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
1e030 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
1e040 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
1e050 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
1e060 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
1e070 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e080 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
1e090 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
1e0a0 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
1e0b0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
1e0c0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1e0d0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
1e0e0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
1e0f0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
1e100 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
1e110 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1e120 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
1e130 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
1e140 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
1e150 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
1e160 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
1e170 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1e180 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
1e190 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
1e1a0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
1e1b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e1c0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
1e1d0 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
1e1e0 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
1e1f0 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
1e200 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
1e210 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
1e220 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
1e230 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
1e240 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
1e250 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
1e260 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
1e270 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
1e280 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
1e290 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
1e2a0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
1e2b0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
1e2c0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
1e2d0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
1e2e0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
1e2f0 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
1e300 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
1e310 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
1e320 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
1e330 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
1e340 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69  d>The maximum si
1e350 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67  ze of any string
1e360 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c   or BLOB or tabl
1e370 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e  e row, in bytes.
1e380 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  <dd>)^.**.** ^(<
1e390 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
1e3a0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
1e3b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1e3c0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
1e3d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
1e3e0 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
1e3f0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1e400 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
1e410 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e420 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1e430 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
1e440 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
1e450 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
1e460 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
1e470 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
1e480 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
1e490 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
1e4a0 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
1e4b0 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
1e4c0 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
1e4d0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1e4e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
1e4f0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
1e500 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
1e510 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73  epth of the pars
1e520 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78  e tree on any ex
1e530 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  pression.</dd>)^
1e540 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1e550 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
1e560 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
1e570 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e580 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
1e590 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
1e5a0 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
1e5b0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1e5c0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1e5d0 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a  T_VDBE_OP</dt>.*
1e5e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e5f0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74  m number of inst
1e600 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69  ructions in a vi
1e610 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72  rtual machine pr
1e620 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f  ogram.** used to
1e630 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51   implement an SQ
1e640 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68  L statement.  Th
1e650 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  is limit is not 
1e660 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66  currently.** enf
1e670 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68  orced, though th
1e680 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65  at might be adde
1e690 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  d in some future
1e6a0 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
1e6b0 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  QLite.</dd>)^.**
1e6c0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1e6d0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
1e6e0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
1e6f0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
1e700 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
1e710 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
1e720 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1e730 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  t>SQLITE_LIMIT_A
1e740 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20  TTACHED</dt>.** 
1e750 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
1e760 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43  number of [ATTAC
1e770 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61 74  H | attached dat
1e780 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a  abases].)^</dd>.
1e790 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  **.** ^(<dt>SQLI
1e7a0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
1e7b0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74  TTERN_LENGTH</dt
1e7c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1e7d0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74  imum length of t
1e7e0 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d  he pattern argum
1e7f0 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45  ent to the [LIKE
1e800 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f  ] or.** [GLOB] o
1e810 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e  perators.</dd>)^
1e820 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  .**.** ^(<dt>SQL
1e830 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1e840 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a  LE_NUMBER</dt>.*
1e850 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
1e860 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f  m index number o
1e870 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72  f any [parameter
1e880 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  ] in an SQL stat
1e890 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ement.)^.**.** ^
1e8a0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
1e8b0 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
1e8c0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1e8d0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
1e8e0 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
1e8f0 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
1e900 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
1e910 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
1e920 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
1e930 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
1e940 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
1e950 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
1e960 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
1e970 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
1e980 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
1e990 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
1e9a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
1e9b0 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
1e9c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
1e9d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
1e9e0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
1e9f0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
1ea00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ea10 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
1ea20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ea30 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
1ea40 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
1ea50 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
1ea60 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
1ea70 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
1ea80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ea90 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
1eaa0 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
1eab0 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
1eac0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
1ead0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
1eae0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
1eaf0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
1eb00 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
1eb10 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
1eb20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41      10../*.** CA
1eb30 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
1eb40 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
1eb50 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  nt.** KEYWORDS: 
1eb60 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  {SQL statement c
1eb70 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54  ompiler}.**.** T
1eb80 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
1eb90 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20   query, it must 
1eba0 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
1ebb0 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
1ebc0 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
1ebd0 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
1ebe0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
1ebf0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
1ec00 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
1ec10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1ec20 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
1ec30 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
1ec40 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
1ec50 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
1ec60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
1ec70 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
1ec80 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
1ec90 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
1eca0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
1ecb0 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
1ecc0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
1ecd0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
1ece0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
1ecf0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
1ed00 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
1ed10 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
1ed20 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
1ed30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
1ed40 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
1ed50 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
1ed60 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
1ed70 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
1ed80 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1ed90 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
1eda0 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
1edb0 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
1edc0 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61   ^If the nByte a
1edd0 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20  rgument is less 
1ede0 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
1edf0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
1ee00 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
1ee10 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1ee20 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f   ^If nByte is no
1ee30 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
1ee40 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
1ee50 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  um.** number of 
1ee60 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
1ee70 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42   zSql.  ^When nB
1ee80 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
1ee90 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
1eea0 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
1eeb0 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
1eec0 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
1eed0 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
1eee0 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
1eef0 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
1ef00 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
1ef10 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
1ef20 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
1ef30 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
1ef40 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
1ef50 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
1ef60 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
1ef70 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
1ef80 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
1ef90 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
1efa0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
1efb0 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
1efc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1efd0 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
1efe0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
1eff0 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
1f000 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
1f010 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  tes..**.** ^If p
1f020 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
1f030 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
1f040 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
1f050 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
1f060 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
1f070 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
1f080 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
1f090 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
1f0a0 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
1f0b0 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
1f0c0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
1f0d0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
1f0e0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
1f0f0 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
1f100 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
1f110 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
1f120 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
1f130 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
1f140 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
1f150 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
1f160 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
1f170 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1f180 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
1f190 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
1f1a0 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
1f1b0 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
1f1c0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
1f1d0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
1f1e0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
1f1f0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
1f200 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
1f210 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
1f220 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
1f230 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
1f240 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
1f250 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
1f260 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
1f270 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
1f280 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1f290 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
1f2a0 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
1f2b0 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
1f2c0 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
1f2d0 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
1f2e0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
1f2f0 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
1f300 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
1f310 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
1f320 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
1f330 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
1f340 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
1f350 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
1f360 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
1f370 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1f380 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
1f390 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
1f3a0 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
1f3b0 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
1f3c0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
1f3d0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
1f3e0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
1f3f0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
1f400 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
1f410 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
1f420 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
1f430 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
1f440 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
1f450 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
1f460 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
1f470 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
1f480 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
1f490 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
1f4a0 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
1f4b0 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
1f4c0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
1f4d0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
1f4e0 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
1f4f0 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
1f500 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
1f510 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
1f520 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
1f530 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
1f540 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
1f550 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
1f560 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
1f570 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
1f580 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
1f590 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
1f5a0 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
1f5b0 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
1f5c0 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
1f5d0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
1f5e0 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
1f5f0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
1f600 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1f610 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
1f620 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
1f630 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
1f640 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
1f650 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
1f660 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
1f670 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
1f680 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1f690 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
1f6a0 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
1f6b0 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
1f6c0 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
1f6d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
1f6e0 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
1f6f0 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
1f700 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
1f710 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
1f720 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
1f730 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
1f740 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
1f750 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
1f760 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
1f770 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
1f780 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
1f790 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1f7a0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
1f7b0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
1f7c0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
1f7d0 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
1f7e0 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
1f7f0 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
1f800 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
1f810 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
1f820 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
1f830 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
1f840 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
1f850 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
1f860 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
1f870 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
1f880 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
1f890 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
1f8a0 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
1f8b0 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
1f8c0 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
1f8d0 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
1f8e0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
1f8f0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
1f900 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
1f910 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
1f920 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
1f930 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
1f940 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
1f950 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
1f960 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
1f970 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
1f980 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
1f990 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1f9a0 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
1f9b0 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
1f9c0 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
1f9d0 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
1f9e0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
1f9f0 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
1fa00 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
1fa10 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
1fa20 45 4e 41 42 4c 45 5f 53 54 41 54 32 5d 20 63 6f  ENABLE_STAT2] co
1fa30 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
1fa40 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
1fa50 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a   the .** </li>.*
1fa60 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54  * </ol>.*/.SQLIT
1fa70 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1fa80 33 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c  3_prepare(.  sql
1fa90 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1faa0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
1fab0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
1fac0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
1fad0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
1fae0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
1faf0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
1fb00 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
1fb10 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
1fb20 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
1fb30 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
1fb40 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
1fb50 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
1fb60 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
1fb70 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
1fb80 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
1fb90 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
1fba0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
1fbb0 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
1fbc0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1fbd0 70 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71  prepare_v2(.  sq
1fbe0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1fbf0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1fc00 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1fc10 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1fc20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1fc30 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e  tement, UTF-8 en
1fc40 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
1fc50 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
1fc60 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
1fc70 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
1fc80 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
1fc90 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
1fca0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
1fcb0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
1fcc0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
1fcd0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
1fce0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
1fcf0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
1fd00 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
1fd10 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1fd20 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
1fd30 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
1fd40 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
1fd50 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
1fd60 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
1fd70 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
1fd80 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
1fd90 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
1fda0 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
1fdb0 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
1fdc0 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
1fdd0 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
1fde0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
1fdf0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
1fe00 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
1fe10 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
1fe20 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
1fe30 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
1fe40 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
1fe50 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  zSql */.);.SQLIT
1fe60 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1fe70 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a  3_prepare16_v2(.
1fe80 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
1fe90 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
1fea0 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
1feb0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
1fec0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
1fed0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
1fee0 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
1fef0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
1ff00 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
1ff10 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
1ff20 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
1ff30 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
1ff40 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
1ff50 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
1ff60 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
1ff70 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
1ff80 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
1ff90 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
1ffa0 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a   of zSql */.);..
1ffb0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ffc0 52 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65  Retrieving State
1ffd0 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e  ment SQL.**.** ^
1ffe0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63  This interface c
1fff0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
20000 74 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63  trieve a saved c
20010 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69  opy of the origi
20020 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20  nal.** SQL text 
20030 75 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61  used to create a
20040 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20050 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74  ment] if that st
20060 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63  atement was.** c
20070 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69  ompiled using ei
20080 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
20090 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
200a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
200b0 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  6_v2()]..*/.SQLI
200c0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
200d0 72 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73  r *sqlite3_sql(s
200e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
200f0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
20100 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20  3REF: Determine 
20110 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  If An SQL Statem
20120 65 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44  ent Writes The D
20130 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54  atabase.**.** ^T
20140 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  he sqlite3_stmt_
20150 72 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65  readonly(X) inte
20160 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72  rface returns tr
20170 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66  ue (non-zero) if
20180 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20  .** and only if 
20190 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
201a0 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73  atement] X makes
201b0 20 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67   no direct chang
201c0 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e  es to.** the con
201d0 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61  tent of the data
201e0 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a  base file..**.**
201f0 20 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c   Note that [appl
20200 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
20210 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f  SQL functions] o
20220 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61  r.** [virtual ta
20230 62 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e  bles] might chan
20240 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
20250 69 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20  indirectly as a 
20260 73 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a  side effect.  .*
20270 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c  * ^(For example,
20280 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
20290 6f 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e  on defines a fun
202a0 63 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74  ction "eval()" t
202b0 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73  hat .** calls [s
202c0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20  qlite3_exec()], 
202d0 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  then the followi
202e0 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ng SQL statement
202f0 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65   would.** change
20300 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
20310 6c 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d  le through side-
20320 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c  effects:.**.** <
20330 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
20340 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76  .**    SELECT ev
20350 61 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20  al('DELETE FROM 
20360 74 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a  t1') FROM t2;.**
20370 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
20380 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62  ote>.**.** But b
20390 65 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45  ecause the [SELE
203a0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f  CT] statement do
203b0 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
203c0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a  e database file.
203d0 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c  ** directly, sql
203e0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
203f0 6c 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c  ly() would still
20400 20 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a   return true.)^.
20410 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69  **.** ^Transacti
20420 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65  on control state
20430 6d 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42  ments such as [B
20440 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c  EGIN], [COMMIT],
20450 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20   [ROLLBACK],.** 
20460 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64  [SAVEPOINT], and
20470 20 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65   [RELEASE] cause
20480 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
20490 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75  adonly() to retu
204a0 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63  rn true,.** sinc
204b0 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73  e the statements
204c0 20 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e   themselves do n
204d0 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69  ot actually modi
204e0 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
204f0 62 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68  but.** rather th
20500 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74  ey control the t
20510 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74  iming of when ot
20520 68 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d  her statements m
20530 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61  odify the .** da
20540 74 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41  tabase.  ^The [A
20550 54 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41  TTACH] and [DETA
20560 43 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61  CH] statements a
20570 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c  lso cause.** sql
20580 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
20590 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74  ly() to return t
205a0 72 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65  rue since, while
205b0 20 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74   those statement
205c0 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  s.** change the 
205d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66  configuration of
205e0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
205f0 65 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20  ection, they do 
20600 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61  not make .** cha
20610 6e 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74  nges to the cont
20620 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
20630 61 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73  ase files on dis
20640 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  k..*/.SQLITE_API
20650 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d   int sqlite3_stm
20660 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  t_readonly(sqlit
20670 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
20680 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20690 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
206a0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
206b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
206c0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
206d0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
206e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
206f0 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
20700 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
20710 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
20720 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
20730 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
20740 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
20750 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
20760 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
20770 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
20780 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
20790 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
207a0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
207b0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
207c0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
207d0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
207e0 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
207f0 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
20800 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
20810 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
20820 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
20830 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
20840 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
20850 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
20860 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
20870 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20880 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
20890 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
208a0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
208b0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
208c0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
208d0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
208e0 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
208f0 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
20900 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
20910 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
20920 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
20930 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
20940 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
20950 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
20960 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
20970 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
20980 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
20990 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
209a0 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
209b0 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
209c0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
209d0 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
209e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
209f0 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
20a00 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
20a10 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
20a20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
20a30 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
20a40 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
20a50 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
20a60 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
20a70 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
20a80 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
20a90 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
20aa0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
20ab0 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
20ac0 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
20ad0 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
20ae0 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
20af0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
20b00 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
20b10 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
20b20 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
20b30 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
20b40 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
20b50 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
20b60 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
20b70 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
20b80 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
20b90 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
20ba0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
20bb0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
20bc0 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
20bd0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
20be0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
20bf0 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
20c00 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
20c10 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
20c20 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
20c30 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
20c40 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
20c50 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
20c60 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
20c70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
20c80 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
20c90 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
20ca0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
20cb0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
20cc0 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
20cd0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
20ce0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
20cf0 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
20d00 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
20d10 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
20d20 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
20d30 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
20d40 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
20d50 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
20d60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
20d70 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
20d80 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
20d90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
20da0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
20db0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
20dc0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
20dd0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
20de0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
20df0 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
20e00 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
20e10 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
20e20 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
20e30 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
20e40 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
20e50 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
20e60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
20e70 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
20e80 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
20e90 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
20ea0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
20eb0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
20ec0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
20ed0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
20ee0 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
20ef0 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
20f00 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
20f10 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
20f20 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
20f30 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
20f40 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
20f50 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
20f60 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
20f70 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
20f80 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
20f90 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
20fa0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
20fb0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
20fc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
20fd0 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
20fe0 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
20ff0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
21000 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
21010 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
21020 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
21030 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
21040 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
21050 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
21060 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
21070 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
21080 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
21090 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
210a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
210b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
210c0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
210d0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
210e0 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
210f0 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
21100 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
21110 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
21120 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
21130 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
21140 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
21150 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
21160 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
21170 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
21180 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
21190 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
211a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
211b0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
211c0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
211d0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
211e0 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
211f0 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
21200 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
21210 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
21220 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
21230 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
21240 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
21250 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
21260 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
21270 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
21280 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
21290 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
212a0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
212b0 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
212c0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
212d0 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
212e0 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
212f0 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
21300 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
21310 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
21320 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
21330 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
21340 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
21350 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
21360 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
21370 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
21380 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
21390 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
213a0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
213b0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
213c0 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
213d0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
213e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
213f0 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
21400 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
21410 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
21420 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
21430 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
21440 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
21450 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
21460 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
21470 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
21480 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
21490 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
214a0 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
214b0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
214c0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
214d0 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
214e0 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
214f0 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
21500 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
21510 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
21520 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
21530 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
21540 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
21550 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
21560 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
21570 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
21580 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
21590 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
215a0 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
215b0 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
215c0 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
215d0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
215e0 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
215f0 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
21600 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
21610 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
21620 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
21630 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
21640 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
21650 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
21660 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
21670 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
21680 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
21690 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
216a0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  eter..**.** ^(In
216b0 20 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20   those routines 
216c0 74 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72  that have a four
216d0 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73  th argument, its
216e0 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
216f0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
21700 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65   in the paramete
21710 72 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a  r.  To be clear:
21720 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68   the value is th
21730 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c  e.** number of <
21740 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74  u>bytes</u> in t
21750 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68  he value, not th
21760 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72  e number of char
21770 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66  acters.)^.** ^If
21780 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
21790 6d 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76  meter is negativ
217a0 65 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  e, the length of
217b0 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a   the string is.*
217c0 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
217d0 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20  bytes up to the 
217e0 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
217f0 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nator..**.** ^Th
21800 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
21810 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
21820 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
21830 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
21840 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
21850 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
21860 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
21870 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
21880 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
21890 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
218a0 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
218b0 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
218c0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
218d0 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
218e0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
218f0 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
21900 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
21910 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a  3_bind_blob(),.*
21920 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
21930 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  ext(), or sqlite
21940 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
21950 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20  fails.  .** ^If 
21960 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
21970 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
21980 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
21990 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
219a0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
219b0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
219c0 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
219d0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
219e0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
219f0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
21a00 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
21a10 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
21a20 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
21a30 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
21a40 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
21a50 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
21a60 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
21a70 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
21a80 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
21a90 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
21aa0 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
21ab0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
21ac0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
21ad0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
21ae0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
21af0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
21b00 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
21b10 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
21b20 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
21b30 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
21b40 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
21b50 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
21b60 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
21b70 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
21b80 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
21b90 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
21ba0 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
21bb0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
21bc0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
21bd0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
21be0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
21bf0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
21c00 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
21c10 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
21c20 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
21c30 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
21c40 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
21c50 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
21c60 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
21c70 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
21c80 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
21c90 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
21ca0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
21cb0 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
21cc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21cd0 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
21ce0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
21cf0 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
21d00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
21d10 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
21d20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
21d30 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
21d40 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
21d50 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
21d60 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
21d70 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
21d80 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
21d90 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
21da0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
21db0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
21dc0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
21dd0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
21de0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
21df0 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
21e00 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
21e10 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
21e20 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
21e30 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
21e40 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
21e50 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
21e60 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
21e70 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
21e80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
21e90 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
21ea0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
21eb0 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
21ec0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
21ed0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
21ee0 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  g..** ^[SQLITE_R
21ef0 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
21f00 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
21f10 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
21f20 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
21f30 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
21f40 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
21f50 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
21f60 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
21f70 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
21f80 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
21f90 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
21fa0 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
21fb0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
21fc0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
21fd0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
21fe0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
21ff0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
22000 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
22010 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
22020 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
22030 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
22040 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
22050 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
22060 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
22070 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ble);.SQLITE_API
22080 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
22090 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
220a0 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
220b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
220c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
220d0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
220e0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
220f0 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
22100 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
22110 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
22120 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  tmt*, int);.SQLI
22130 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
22140 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
22150 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
22160 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
22170 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
22180 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
22190 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
221a0 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
221b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
221c0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
221d0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
221e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
221f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
22200 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
22210 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
22220 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
22230 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
22240 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
22250 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
22260 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
22270 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
22280 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
22290 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54  ameters.**.** ^T
222a0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
222b0 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
222c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
222d0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
222e0 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
222f0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
22300 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
22310 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
22320 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
22330 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
22340 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
22350 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
22360 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
22370 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
22380 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
22390 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
223a0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
223b0 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
223c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
223d0 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
223e0 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
223f0 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
22400 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
22410 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
22420 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
22430 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
22440 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
22450 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
22460 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
22470 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
22480 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
22490 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
224a0 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
224b0 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
224c0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
224d0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
224e0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
224f0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
22500 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
22510 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
22520 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
22530 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
22540 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
22550 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
22560 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
22570 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
22580 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22590 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
225a0 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20  Parameter.**.** 
225b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
225c0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
225d0 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
225e0 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
225f0 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
22600 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
22610 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
22620 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
22630 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
22640 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
22650 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
22660 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
22670 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
22680 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
22690 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
226a0 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
226b0 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
226c0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
226d0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
226e0 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
226f0 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
22700 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
22710 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
22720 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
22730 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
22740 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
22750 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
22760 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
22770 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
22780 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
22790 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
227a0 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
227b0 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
227c0 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
227d0 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
227e0 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
227f0 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
22800 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
22810 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
22820 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
22830 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
22840 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
22850 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
22860 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
22870 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
22880 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
22890 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
228a0 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
228b0 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
228c0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
228d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
228e0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
228f0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
22900 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
22910 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
22920 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
22930 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
22940 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
22950 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
22960 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
22970 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
22980 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
22990 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
229a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
229b0 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
229c0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
229d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
229e0 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
229f0 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
22a00 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52  en Name.**.** ^R
22a10 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
22a20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
22a30 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
22a40 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
22a50 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
22a60 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
22a70 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
22a80 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
22a90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
22aa0 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
22ab0 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
22ac0 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
22ad0 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
22ae0 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
22af0 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
22b00 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
22b10 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
22b20 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
22b30 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
22b40 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
22b50 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
22b60 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
22b70 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
22b80 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
22b90 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
22ba0 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
22bb0 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
22bc0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
22bd0 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
22be0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
22bf0 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
22c00 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
22c10 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
22c20 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
22c30 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
22c40 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
22c50 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
22c60 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
22c70 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
22c80 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
22c90 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
22ca0 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
22cb0 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
22cc0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
22cd0 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
22ce0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
22cf0 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
22d00 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
22d10 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
22d20 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
22d30 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
22d40 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
22d50 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49  to NULL..*/.SQLI
22d60 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
22d70 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
22d80 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
22d90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
22da0 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
22db0 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
22dc0 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75   Set.**.** ^Retu
22dd0 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
22de0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
22df0 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
22e00 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
22e10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
22e20 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
22e30 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
22e40 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
22e50 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
22e60 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
22e70 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
22e80 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
22e90 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
22ea0 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
22eb0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  ount()].*/.SQLIT
22ec0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
22ed0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
22ee0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
22ef0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
22f00 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
22f10 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
22f20 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  et.**.** ^These 
22f30 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
22f40 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
22f50 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
22f60 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
22f70 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
22f80 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
22f90 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
22fa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
22fb0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
22fc0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
22fd0 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
22fe0 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
22ff0 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
23000 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
23010 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
23020 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
23030 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
23040 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
23050 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
23060 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
23070 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
23080 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
23090 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
230a0 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
230b0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
230c0 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
230d0 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
230e0 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
230f0 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
23100 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
23110 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
23120 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
23130 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
23140 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
23150 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
23160 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
23170 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
23180 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
23190 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
231a0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
231b0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
231c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
231d0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
231e0 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
231f0 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
23200 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
23210 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
23220 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
23230 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
23240 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
23250 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
23260 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
23270 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
23280 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
23290 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
232a0 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
232b0 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
232c0 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
232d0 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
232e0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
232f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
23300 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
23310 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
23320 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
23330 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
23340 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
23350 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
23360 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
23370 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
23380 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
23390 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
233a0 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
233b0 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
233c0 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
233d0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
233e0 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ext..*/.SQLITE_A
233f0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
23400 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
23410 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
23420 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45  , int N);.SQLITE
23430 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
23440 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23450 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
23460 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
23470 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
23480 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
23490 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
234a0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
234b0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
234c0 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
234d0 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
234e0 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
234f0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
23500 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
23510 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
23520 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
23530 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
23540 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
23550 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
23560 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
23570 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
23580 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
23590 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
235a0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
235b0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
235c0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
235d0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
235e0 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
235f0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
23600 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
23610 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
23620 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
23630 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
23640 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
23650 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
23660 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
23670 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
23680 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
23690 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
236a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
236b0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
236c0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
236d0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
236e0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
236f0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
23700 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
23710 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
23720 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
23730 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
23740 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
23750 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
23760 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
23770 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
23780 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
23790 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
237a0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
237b0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
237c0 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
237d0 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
237e0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
237f0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
23800 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
23810 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
23820 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
23830 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
23840 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
23850 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
23860 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
23870 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
23880 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
23890 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
238a0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
238b0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
238c0 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
238d0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
238e0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
238f0 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
23900 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
23910 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
23920 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
23930 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
23940 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
23950 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
23960 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
23970 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
23980 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
23990 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
239a0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
239b0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
239c0 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
239d0 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
239e0 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
239f0 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
23a00 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
23a10 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
23a20 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
23a30 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
23a40 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
23a50 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
23a60 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
23a70 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
23a80 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
23a90 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
23aa0 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
23ab0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
23ac0 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
23ad0 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
23ae0 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
23af0 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
23b00 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
23b10 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
23b20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
23b30 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
23b40 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
23b50 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
23b60 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
23b70 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
23b80 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
23b90 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
23ba0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
23bb0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
23bc0 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
23bd0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
23be0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
23bf0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
23c00 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
23c10 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
23c20 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
23c30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
23c40 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
23c50 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
23c60 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
23c70 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
23c80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
23c90 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
23ca0 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
23cb0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
23cc0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
23cd0 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ned..*/.SQLITE_A
23ce0 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
23cf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
23d00 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
23d10 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
23d20 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
23d30 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
23d40 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
23d50 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
23d60 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
23d70 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
23d80 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
23d90 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
23da0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
23db0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
23dc0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
23dd0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
23de0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
23df0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
23e00 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
23e10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
23e20 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
23e30 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
23e40 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
23e50 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
23e60 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
23e70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
23e80 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
23e90 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
23ea0 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
23eb0 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
23ec0 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
23ed0 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
23ee0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
23ef0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
23f00 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
23f10 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
23f20 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
23f30 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
23f40 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
23f50 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
23f60 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
23f70 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
23f80 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
23f90 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
23fa0 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
23fb0 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
23fc0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
23fd0 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
23fe0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
23ff0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
24000 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
24010 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
24020 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
24030 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
24040 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
24050 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
24060 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
24070 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
24080 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
24090 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
240a0 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
240b0 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
240c0 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
240d0 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
240e0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
240f0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
24100 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
24110 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
24120 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
24130 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
24140 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
24150 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
24160 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
24170 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
24180 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
24190 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
241a0 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
241b0 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
241c0 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
241d0 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
241e0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
241f0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
24200 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
24210 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
24220 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
24230 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
24240 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
24250 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
24260 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
24270 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
24280 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
24290 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
242a0 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
242b0 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
242c0 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
242d0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
242e0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
242f0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
24300 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
24310 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
24320 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
24330 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
24340 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
24350 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
24360 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
24370 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
24380 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
24390 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
243a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
243b0 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
243c0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74  tement.**.** Aft
243d0 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
243e0 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
243f0 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
24400 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
24410 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
24420 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
24430 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
24440 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
24450 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
24460 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
24470 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
24480 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
24490 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
244a0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
244b0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
244c0 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
244d0 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
244e0 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
244f0 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
24500 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
24510 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
24520 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
24530 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
24540 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
24550 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
24560 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
24570 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
24580 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
24590 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
245a0 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
245b0 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
245c0 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
245d0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
245e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
245f0 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
24600 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
24610 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
24620 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
24630 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
24640 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
24650 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
24660 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
24670 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
24680 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
24690 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
246a0 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
246b0 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
246c0 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
246d0 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
246e0 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
246f0 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
24700 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
24710 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
24720 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
24730 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
24740 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
24750 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
24760 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
24770 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
24780 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
24790 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
247a0 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
247b0 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
247c0 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
247d0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
247e0 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
247f0 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
24800 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
24810 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
24820 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
24830 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
24840 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
24850 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
24860 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
24870 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
24880 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
24890 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
248a0 20 77 69 74 68 69 6e 20 61 0a 2a 2a 20 65 78 70   within a.** exp
248b0 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
248c0 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c  n then you shoul
248d0 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74  d rollback the t
248e0 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72  ransaction befor
248f0 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e  e.** continuing.
24900 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
24910 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74  DONE] means that
24920 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68   the statement h
24930 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65 63  as finished exec
24940 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73  uting.** success
24950 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f  fully.  sqlite3_
24960 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
24970 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
24980 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61  n on this virtua
24990 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74  l.** machine wit
249a0 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69  hout first calli
249b0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
249c0 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68  t()] to reset th
249d0 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63  e virtual.** mac
249e0 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73  hine back to its
249f0 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a   initial state..
24a00 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51  **.** ^If the SQ
24a10 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e  L statement bein
24a20 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75 72  g executed retur
24a30 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65  ns any data, the
24a40 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a  n [SQLITE_ROW].*
24a50 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65 61  * is returned ea
24a60 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f  ch time a new ro
24a70 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65 61  w of data is rea
24a80 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e  dy for processin
24a90 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c  g by the.** call
24aa0 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d  er. The values m
24ab0 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20 75  ay be accessed u
24ac0 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e  sing the [column
24ad0 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
24ae0 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  s]..** sqlite3_s
24af0 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20  tep() is called 
24b00 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76  again to retriev
24b10 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f  e the next row o
24b20 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  f data..**.** ^[
24b30 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65  SQLITE_ERROR] me
24b40 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74  ans that a run-t
24b50 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68 20  ime error (such 
24b60 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a  as a constraint.
24b70 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61  ** violation) ha
24b80 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c  s occurred.  sql
24b90 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75  ite3_step() shou
24ba0 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64  ld not be called
24bb0 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65   again on.** the
24bc0 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d   VM. More inform
24bd0 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75  ation may be fou
24be0 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  nd by calling [s
24bf0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d  qlite3_errmsg()]
24c00 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c  ..** ^With the l
24c10 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c  egacy interface,
24c20 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63   a more specific
24c30 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72   error code (for
24c40 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51   example,.** [SQ
24c50 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c  LITE_INTERRUPT],
24c60 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
24c70 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  , [SQLITE_CORRUP
24c80 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68  T], and so forth
24c90 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61  ).** can be obta
24ca0 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ined by calling 
24cb0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
24cc0 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ] on the.** [pre
24cd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24ce0 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  .  ^In the "v2" 
24cf0 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68  interface,.** th
24d00 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
24d10 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65  error code is re
24d20 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20  turned directly 
24d30 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
24d40 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45  )..**.** [SQLITE
24d50 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74  _MISUSE] means t
24d60 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f 75  hat the this rou
24d70 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20  tine was called 
24d80 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e  inappropriately.
24d90 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20 77  .** Perhaps it w
24da0 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  as called on a [
24db0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
24dc0 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20  nt] that has.** 
24dd0 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71  already been [sq
24de0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c  lite3_finalize |
24df0 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f   finalized] or o
24e00 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a  n one that had.*
24e10 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  * previously ret
24e20 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52  urned [SQLITE_ER
24e30 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROR] or [SQLITE_
24e40 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f  DONE].  Or it co
24e50 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61  uld.** be the ca
24e60 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d 65  se that the same
24e70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
24e80 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73  tion is being us
24e90 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20  ed by two or.** 
24ea0 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74 20  more threads at 
24eb0 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20  the same moment 
24ec0 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46  in time..**.** F
24ed0 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20  or all versions 
24ee0 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20  of SQLite up to 
24ef0 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e  and including 3.
24f00 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74  6.23.1, a call t
24f10 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  o.** [sqlite3_re
24f20 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75 69  set()] was requi
24f30 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  red after sqlite
24f40 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e 65  3_step() returne
24f50 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74  d anything.** ot
24f60 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
24f70 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79  _ROW] before any
24f80 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f   subsequent invo
24f90 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c  cation of.** sql
24fa0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61  ite3_step().  Fa
24fb0 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20 74  ilure to reset t
24fc0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
24fd0 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20  ement using .** 
24fe0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
24ff0 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69  ] would result i
25000 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  n an [SQLITE_MIS
25010 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d  USE] return from
25020 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
25030 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20 76  ().  But after v
25040 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c  ersion 3.6.23.1,
25050 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
25060 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67  began.** calling
25070 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
25080 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  )] automatically
25090 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73   in this circums
250a0 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20  tance rather.** 
250b0 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b  than returning [
250c0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
250d0 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e   This is not con
250e0 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74  sidered a compat
250f0 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b  ibility.** break
25100 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70 70   because any app
25110 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76  lication that ev
25120 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20 53  er receives an S
25130 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72  QLITE_MISUSE err
25140 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20  or.** is broken 
25150 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20  by definition.  
25160 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54  The [SQLITE_OMIT
25170 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70  _AUTORESET] comp
25180 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a  ile-time option.
25190 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ** can be used t
251a0 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65  o restore the le
251b0 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a  gacy behavior..*
251c0 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e  *.** <b>Goofy In
251d0 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f  terface Alert:</
251e0 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79  b> In the legacy
251f0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20   interface, the 
25200 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a  sqlite3_step().*
25210 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65 74  * API always ret
25220 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65  urns a generic e
25230 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49  rror code, [SQLI
25240 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f  TE_ERROR], follo
25250 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f  wing any.** erro
25260 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  r other than [SQ
25270 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b  LITE_BUSY] and [
25280 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
25290 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a   You must call.*
252a0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
252b0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
252c0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f  finalize()] in o
252d0 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65  rder to find one
252e0 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69   of the.** speci
252f0 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  fic [error codes
25300 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64 65  ] that better de
25310 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
25320 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74  r..** We admit t
25330 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67 6f  hat this is a go
25340 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65  ofy design.  The
25350 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65   problem has bee
25360 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20  n fixed.** with 
25370 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
25380 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70  ce.  If you prep
25390 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20  are all of your 
253a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
253b0 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b  * using either [
253c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
253d0 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
253e0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
253f0 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20  ] instead.** of 
25400 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69  the legacy [sqli
25410 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
25420 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
25430 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61  are16()] interfa
25440 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ces,.** then the
25450 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b   more specific [
25460 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65  error codes] are
25470 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74   returned direct
25480 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ly.** by sqlite3
25490 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75 73  _step().  The us
254a0 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e  e of the "v2" in
254b0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
254c0 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  mended..*/.SQLIT
254d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
254e0 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
254f0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
25500 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
25510 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
25520 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
25530 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
25540 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
25550 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
25560 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
25570 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
25580 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
25590 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
255a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
255b0 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
255c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
255d0 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
255e0 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
255f0 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
25600 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
25610 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
25620 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
25630 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
25640 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
25650 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
25660 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
25670 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
25680 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
25690 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
256a0 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
256b0 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
256c0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
256d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
256e0 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  t()].*/.SQLITE_A
256f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  PI int sqlite3_d
25700 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  ata_count(sqlite
25710 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
25720 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25730 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74   Fundamental Dat
25740 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  atypes.** KEYWOR
25750 44 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  DS: SQLITE_TEXT.
25760 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61  **.** ^(Every va
25770 6c 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61  lue in SQLite ha
25780 73 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75  s one of five fu
25790 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79  ndamental dataty
257a0 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  pes:.**.** <ul>.
257b0 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73  ** <li> 64-bit s
257c0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a  igned integer.**
257d0 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45   <li> 64-bit IEE
257e0 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  E floating point
257f0 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20   number.** <li> 
25800 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42  string.** <li> B
25810 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c  LOB.** <li> NULL
25820 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a  .** </ul>)^.**.*
25830 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
25840 73 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20  s are codes for 
25850 65 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79  each of those ty
25860 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  pes..**.** Note 
25870 74 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f  that the SQLITE_
25880 54 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61  TEXT constant wa
25890 73 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53  s also used in S
258a0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a  QLite version 2.
258b0 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74  ** for a complet
258c0 65 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65  ely different me
258d0 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65  aning.  Software
258e0 20 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69   that links agai
258f0 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69  nst both.** SQLi
25900 74 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64  te version 2 and
25910 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
25920 33 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c  3 should use SQL
25930 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a  ITE3_TEXT, not.*
25940 2a 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a  * SQLITE_TEXT..*
25950 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
25960 5f 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66  _INTEGER  1.#def
25970 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ine SQLITE_FLOAT
25980 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
25990 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a  LITE_BLOB     4.
259a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
259b0 55 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66  ULL     5.#ifdef
259c0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75   SQLITE_TEXT.# u
259d0 6e 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  ndef SQLITE_TEXT
259e0 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20  .#else.# define 
259f0 53 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20  SQLITE_TEXT     
25a00 33 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  3.#endif.#define
25a10 20 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20   SQLITE3_TEXT   
25a20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    3../*.** CAPI3
25a30 52 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75  REF: Result Valu
25a40 65 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a  es From A Query.
25a50 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f  ** KEYWORDS: {co
25a60 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
25a70 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65  tions}.**.** The
25a80 73 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d  se routines form
25a90 20 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74   the "result set
25aa0 22 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a  " interface..**.
25ab0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
25ac0 65 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  es return inform
25ad0 61 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69  ation about a si
25ae0 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  ngle column of t
25af0 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65  he current.** re
25b00 73 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75  sult row of a qu
25b10 65 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20  ery.  ^In every 
25b20 63 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61  case the first a
25b30 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
25b40 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
25b50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25b60 6e 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e  nt] that is bein
25b70 67 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65  g evaluated (the
25b80 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
25b90 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74  .** that was ret
25ba0 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  urned from [sqli
25bb0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
25bc0 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20  ] or one of its 
25bd0 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64  variants).** and
25be0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
25bf0 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
25c00 78 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20  x of the column 
25c10 66 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d  for which inform
25c20 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
25c30 62 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68  be returned. ^Th
25c40 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d  e leftmost colum
25c50 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
25c60 73 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65  set has the inde
25c70 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d  x 0..** ^The num
25c80 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
25c90 6e 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e  n the result can
25ca0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75   be determined u
25cb0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
25cc0 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d  _column_count()]
25cd0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53  ..**.** If the S
25ce0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  QL statement doe
25cf0 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
25d00 70 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64  point to a valid
25d10 20 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a   row, or if the.
25d20 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20  ** column index 
25d30 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
25d40 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75   the result is u
25d50 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  ndefined..** The
25d60 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20  se routines may 
25d70 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77  only be called w
25d80 68 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63  hen the most rec
25d90 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
25da0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25db0 68 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51  has returned [SQ
25dc0 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65  LITE_ROW] and ne
25dd0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
25de0 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b  3_reset()] nor [
25df0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
25e00 28 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61  ()] have been ca
25e10 6c 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c  lled subsequentl
25e20 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20  y..** If any of 
25e30 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
25e40 72 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  re called after 
25e50 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
25e60 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
25e70 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
25e80 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73  after [sqlite3_s
25e90 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72  tep()] has retur
25ea0 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67  ned.** something
25eb0 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
25ec0 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65  ITE_ROW], the re
25ed0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
25ee0 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69  ned..** If [sqli
25ef0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b  te3_step()] or [
25f00 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
25f10 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
25f20 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20  alize()].** are 
25f30 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69  called from a di
25f40 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77  fferent thread w
25f50 68 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73  hile any of thes
25f60 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72  e routines.** ar
25f70 65 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20  e pending, then 
25f80 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
25f90 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a  undefined..**.**
25fa0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
25fb0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74  lumn_type() rout
25fc0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ine returns the.
25fd0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  ** [SQLITE_INTEG
25fe0 45 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f  ER | datatype co
25ff0 64 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74  de] for the init
26000 69 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a  ial data type.**
26010 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63   of the result c
26020 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74  olumn.  ^The ret
26030 75 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f  urned value is o
26040 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e  ne of [SQLITE_IN
26050 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  TEGER],.** [SQLI
26060 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49  TE_FLOAT], [SQLI
26070 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54  TE_TEXT], [SQLIT
26080 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c  E_BLOB], or [SQL
26090 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20  ITE_NULL].  The 
260a0 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
260b0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
260c0 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e  umn_type() is on
260d0 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66  ly meaningful if
260e0 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76   no type.** conv
260f0 65 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63  ersions have occ
26100 75 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62  urred as describ
26110 65 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72  ed below.  After
26120 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
26130 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  on,.** the value
26140 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
26150 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
26160 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
26170 20 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73    Future.** vers
26180 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
26190 61 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65  ay change the be
261a0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
261b0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a  3_column_type().
261c0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74  ** following a t
261d0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ype conversion..
261e0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
261f0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
26200 72 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74  r UTF-8 string t
26210 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
26220 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a  column_bytes().*
26230 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
26240 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
26250 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
26260 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
26270 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
26280 69 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  is a UTF-16 stri
26290 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
262a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
262b0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
262c0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20  string to UTF-8 
262d0 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73  and then returns
262e0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
262f0 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ytes..** ^If the
26300 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d   result is a num
26310 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20  eric value then 
26320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
26330 79 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b  ytes() uses.** [
26340 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
26350 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
26360 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
26370 54 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20  TF-8 string and 
26380 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
26390 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
263a0 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
263b0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
263c0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
263d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
263e0 74 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65  tes() returns ze
263f0 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ro..**.** ^If th
26400 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
26410 4f 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72  OB or UTF-16 str
26420 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
26430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
26440 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  s16().** routine
26450 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
26460 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
26470 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72  that BLOB or str
26480 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
26490 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d  result is a UTF-
264a0 38 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73  8 string, then s
264b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
264c0 74 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73  tes16() converts
264d0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
264e0 6f 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65  o UTF-16 and the
264f0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
26500 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
26510 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
26520 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
26530 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
26540 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
26550 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
26560 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
26570 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
26580 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36  alue to a UTF-16
26590 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
265a0 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
265b0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
265c0 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
265d0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
265e0 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
265f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
26600 36 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  6() returns zero
26610 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c  ..**.** ^The val
26620 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ues returned by 
26630 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26640 62 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a  bytes()] and .**
26650 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
26660 5f 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e  _bytes16()] do n
26670 6f 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a  ot include the z
26680 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20  ero terminators 
26690 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66  at the end.** of
266a0 20 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46   the string.  ^F
266b0 6f 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20  or clarity: the 
266c0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
266d0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
266e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61  olumn_bytes()] a
266f0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  nd [sqlite3_colu
26700 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72  mn_bytes16()] ar
26710 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  e the number of.
26720 2a 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  ** bytes in the 
26730 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20  string, not the 
26740 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
26750 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72  ters..**.** ^Str
26760 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79  ings returned by
26770 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
26780 74 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74  text() and sqlit
26790 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
267a0 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74  (),.** even empt
267b0 79 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61  y strings, are a
267c0 6c 77 61 79 73 20 7a 65 72 6f 20 74 65 72 6d 69  lways zero termi
267d0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74  nated.  ^The ret
267e0 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f  urn.** value fro
267f0 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  m sqlite3_column
26800 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65  _blob() for a ze
26810 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69  ro-length BLOB i
26820 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
26830 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a  ..**.** ^The obj
26840 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  ect returned by 
26850 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26860 76 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a  value()] is an.*
26870 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
26880 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
26890 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74  ject.  An unprot
268a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
268b0 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61  lue object.** ma
268c0 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77  y only be used w
268d0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  ith [sqlite3_bin
268e0 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  d_value()] and [
268f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
26900 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74  alue()]..** If t
26910 68 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  he [unprotected 
26920 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
26930 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62  bject returned b
26940 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
26950 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
26960 20 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68   used in any oth
26970 65 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e  er way, includin
26980 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f  g calls.** to ro
26990 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
269a0 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29  ite3_value_int()
269b0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
269c0 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
269d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
269e0 62 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74  bytes()], then t
269f0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
26a00 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
26a10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
26a20 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72  ttempt to conver
26a30 74 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72  t the value wher
26a40 65 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20  e appropriate.  
26a50 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c  ^For.** example,
26a60 20 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   if the internal
26a70 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
26a80 69 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74  is FLOAT and a t
26a90 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ext result.** is
26aa0 20 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c   requested, [sql
26ab0 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
26ac0 20 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61   is used interna
26ad0 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74  lly to perform t
26ae0 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  he.** conversion
26af0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
26b00 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67   ^(The following
26b10 20 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74   table details t
26b20 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a  he conversions.*
26b30 2a 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69  * that are appli
26b40 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ed:.**.** <block
26b50 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65  quote>.** <table
26b60 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20   border="1">.** 
26b70 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61  <tr><th> Interna
26b80 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52  l<br>Type <th> R
26b90 65 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65  equested<br>Type
26ba0 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f   <th>  Conversio
26bb0 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  n.**.** <tr><td>
26bc0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49    NULL    <td> I
26bd0 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65  NTEGER   <td> Re
26be0 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72  sult is 0.** <tr
26bf0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
26c00 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
26c10 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30  d> Result is 0.0
26c20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
26c30 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  LL    <td>   TEX
26c40 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  T    <td> Result
26c50 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
26c60 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
26c70 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  LL    <td>   BLO
26c80 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  B    <td> Result
26c90 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   is NULL pointer
26ca0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
26cb0 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
26cc0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
26cd0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
26ce0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
26cf0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
26d00 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
26d10 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
26d20 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
26d30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
26d40 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
26d50 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
26d60 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
26d70 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
26d80 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
26d90 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
26da0 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e  from float to in
26db0 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  teger.** <tr><td
26dc0 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20  >  FLOAT   <td> 
26dd0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
26de0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
26df0 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c  f the float.** <
26e00 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
26e10 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
26e20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f  <td> Same as FLO
26e30 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e  AT->TEXT.** <tr>
26e40 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
26e50 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
26e60 3e 20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  > Use atoi().** 
26e70 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
26e80 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
26e90 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29   <td> Use atof()
26ea0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
26eb0 58 54 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  XT    <td>   BLO
26ec0 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61  B    <td> No cha
26ed0 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  nge.** <tr><td> 
26ee0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e   BLOB    <td> IN
26ef0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
26f00 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68 65  vert to TEXT the
26f10 6e 20 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20  n use atoi().** 
26f20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
26f30 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
26f40 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
26f50 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
26f60 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
26f70 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
26f80 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
26f90 64 64 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e  dd a zero termin
26fa0 61 74 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a  ator if needed.*
26fb0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
26fc0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
26fd0 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62  .** The table ab
26fe0 6f 76 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65  ove makes refere
26ff0 6e 63 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20  nce to standard 
27000 43 20 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69  C library functi
27010 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e  ons atoi().** an
27020 64 20 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74  d atof().  SQLit
27030 65 20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c  e does not reall
27040 79 20 75 73 65 20 74 68 65 73 65 20 66 75 6e 63  y use these func
27050 74 69 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69  tions.  It has i
27060 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61  ts.** own equiva
27070 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f  lent internal ro
27080 75 74 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f  utines.  The ato
27090 69 28 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e  i() and atof() n
270a0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64  ames are.** used
270b0 20 69 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f   in the table fo
270c0 72 20 62 72 65 76 69 74 79 20 61 6e 64 20 62 65  r brevity and be
270d0 63 61 75 73 65 20 74 68 65 79 20 61 72 65 20 66  cause they are f
270e0 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a  amiliar to most.
270f0 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73  ** C programmers
27100 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
27110 74 20 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76  t when type conv
27120 65 72 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70  ersions occur, p
27130 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
27140 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c   by prior.** cal
27150 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
27160 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c  lumn_blob(), sql
27170 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
27180 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71  (), and/or.** sq
27190 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
271a0 74 31 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76  t16() may be inv
271b0 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70  alidated..** Typ
271c0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e  e conversions an
271d0 64 20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69  d pointer invali
271e0 64 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63  dations might oc
271f0 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f  cur.** in the fo
27200 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a  llowing cases:.*
27210 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
27220 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
27230 6e 74 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20  ntent is a BLOB 
27240 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
27250 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20  mn_text() or.** 
27260 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
27270 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
27280 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d  called.  A zero-
27290 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74  terminator might
272a0 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f  .**      need to
272b0 20 62 65 20 61 64 64 65 64 20 74 6f 20 74 68 65   be added to the
272c0 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a   string.</li>.**
272d0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
272e0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
272f0 2d 38 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  -8 text and sqli
27300 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
27310 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  16() or.**      
27320 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27330 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
27340 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20  d.  The content 
27350 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
27360 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46  d.**      to UTF
27370 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  -16.</li>.** <li
27380 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
27390 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20  ntent is UTF-16 
273a0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
273b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
273c0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
273d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
273e0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
273f0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
27400 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
27410 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69     to UTF-8.</li
27420 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
27430 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65   ^Conversions be
27440 74 77 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61  tween UTF-16be a
27450 6e 64 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20  nd UTF-16le are 
27460 61 6c 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70  always done in p
27470 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e  lace and do.** n
27480 6f 74 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20  ot invalidate a 
27490 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74  prior pointer, t
274a0 68 6f 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20  hough of course 
274b0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
274c0 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61  he buffer.** tha
274d0 74 20 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e  t the prior poin
274e0 74 65 72 20 72 65 66 65 72 65 6e 63 65 73 20 77  ter references w
274f0 69 6c 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f  ill have been mo
27500 64 69 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b  dified.  Other k
27510 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65  inds.** of conve
27520 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69  rsion are done i
27530 6e 20 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20  n place when it 
27540 69 73 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74  is possible, but
27550 20 73 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a   sometimes they.
27560 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69  ** are not possi
27570 62 6c 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65  ble and in those
27580 20 63 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69   cases prior poi
27590 6e 74 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69  nters are invali
275a0 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  dated..**.** The
275b0 20 73 61 66 65 73 74 20 61 6e 64 20 65 61 73 69   safest and easi
275c0 65 73 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20  est to remember 
275d0 70 6f 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76  policy is to inv
275e0 6f 6b 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  oke these routin
275f0 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20  es.** in one of 
27600 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61  the following wa
27610 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ys:.**.** <ul>.*
27620 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
27630 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c  olumn_text() fol
27640 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33  lowed by sqlite3
27650 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c  _column_bytes()<
27660 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c  /li>.**  <li>sql
27670 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
27680 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
27690 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
276a0 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c  tes()</li>.**  <
276b0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
276c0 6e 5f 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f  n_text16() follo
276d0 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
276e0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c  olumn_bytes16()<
276f0 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
27700 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
27710 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63  ds, you should c
27720 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  all sqlite3_colu
27730 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71  mn_text(),.** sq
27740 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
27750 62 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f  b(), or sqlite3_
27760 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
27770 66 69 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74  first to force t
27780 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74  he result.** int
27790 6f 20 74 68 65 20 64 65 73 69 72 65 64 20 66 6f  o the desired fo
277a0 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b  rmat, then invok
277b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
277c0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73  _bytes() or.** s
277d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
277e0 74 65 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20  tes16() to find 
277f0 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
27800 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20  result.  Do not 
27810 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20  mix calls.** to 
27820 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27830 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
27840 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77  _column_blob() w
27850 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ith calls to.** 
27860 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27870 79 74 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f  ytes16(), and do
27880 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74   not mix calls t
27890 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
278a0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74  _text16().** wit
278b0 68 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  h calls to sqlit
278c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
278d0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f  )..**.** ^The po
278e0 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20  inters returned 
278f0 61 72 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20  are valid until 
27900 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
27910 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64  n occurs as.** d
27920 65 73 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20  escribed above, 
27930 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65  or until [sqlite
27940 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
27950 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
27960 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
27970 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c  nalize()] is cal
27980 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72  led.  ^The memor
27990 79 20 73 70 61 63 65 20 75 73 65 64 20 74 6f 20  y space used to 
279a0 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20  hold strings.** 
279b0 61 6e 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65  and BLOBs is fre
279c0 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
279d0 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e  .  Do <b>not</b>
279e0 20 70 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65   pass the pointe
279f0 72 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b  rs returned.** [
27a00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27a10 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
27a20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
27a30 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
27a40 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
27a50 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
27a60 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
27a70 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
27a80 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
27a90 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
27aa0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
27ab0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
27ac0 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
27ad0 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
27ae0 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
27af0 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
27b00 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
27b10 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
27b20 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
27b30 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
27b40 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
27b50 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
27b60 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
27b70 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c  NOMEM].)^.*/.SQL
27b80 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
27b90 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
27ba0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
27bb0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
27bc0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
27bd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27be0 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74  bytes(sqlite3_st
27bf0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
27c00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27c10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
27c20 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74  tes16(sqlite3_st
27c30 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
27c40 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c  SQLITE_API doubl
27c50 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
27c60 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
27c70 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
27c80 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
27c90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27ca0 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  int(sqlite3_stmt
27cb0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
27cc0 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
27cd0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63  _int64 sqlite3_c
27ce0 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69  olumn_int64(sqli
27cf0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
27d00 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
27d10 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20   const unsigned 
27d20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
27d30 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65  lumn_text(sqlite
27d40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
27d50 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  l);.SQLITE_API c
27d60 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
27d70 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
27d80 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
27d90 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
27da0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
27db0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
27dc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
27dd0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
27de0 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  PI sqlite3_value
27df0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27e00 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
27e10 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
27e20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27e30 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
27e40 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
27e50 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
27e60 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
27e70 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
27e80 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
27e90 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
27ea0 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
27eb0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
27ec0 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
27ed0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
27ee0 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
27ef0 73 20 6f 72 0a 2a 2a 20 6f 72 20 69 66 20 74 68  s or.** or if th
27f00 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
27f10 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
27f20 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
27f30 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
27f40 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
27f50 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
27f60 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
27f70 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
27f80 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
27f90 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
27fa0 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
27fb0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
27fc0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
27fd0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
27fe0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
27ff0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
28000 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
28010 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
28020 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
28030 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
28040 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
28050 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
28060 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
28070 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
28080 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
28090 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
280a0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
280b0 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
280c0 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
280d0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
280e0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
280f0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
28100 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
28110 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
28120 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
28130 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
28140 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
28150 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
28160 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
28170 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
28180 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
28190 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
281a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
281b0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
281c0 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
281d0 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
281e0 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
281f0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
28200 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
28210 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
28220 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
28230 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
28240 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
28250 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
28260 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
28270 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
28280 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
28290 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
282a0 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
282b0 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
282c0 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
282d0 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
282e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
282f0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
28300 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
28310 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
28320 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
28330 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
28340 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
28350 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
28360 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
28370 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
28380 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
28390 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
283a0 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
283b0 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
283c0 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
283d0 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
283e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
283f0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
28400 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
28410 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
28420 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
28430 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
28440 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
28450 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
28460 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
28470 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
28480 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
28490 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
284a0 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
284b0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
284c0 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
284d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
284e0 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
284f0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
28500 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
28510 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
28520 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
28530 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
28540 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
28550 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28560 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
28570 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
28580 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
28590 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
285a0 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
285b0 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
285c0 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
285d0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
285e0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
285f0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
28600 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
28610 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
28620 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
28630 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
28640 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
28650 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
28660 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
28670 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
28680 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
28690 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
286a0 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
286b0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
286c0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
286d0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
286e0 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
286f0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
28700 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
28710 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
28720 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
28730 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
28740 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
28750 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
28760 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28770 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
28780 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
28790 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
287a0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
287b0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
287c0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
287d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
287e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
287f0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
28800 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28810 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
28820 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
28830 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
28840 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
28850 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
28860 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
28870 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
28880 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
28890 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
288a0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
288b0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
288c0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
288d0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
288e0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
288f0 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
28900 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
28910 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
28920 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
28930 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
28940 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
28950 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
28960 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
28970 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
28980 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
28990 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
289a0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
289b0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
289c0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
289d0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
289e0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
289f0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
28a00 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
28a10 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
28a20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
28a30 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
28a40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
28a50 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
28a60 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
28a70 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
28a80 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28a90 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
28aa0 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
28ab0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
28ac0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
28ad0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
28ae0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
28af0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
28b00 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
28b10 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
28b20 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
28b30 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
28b40 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
28b50 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
28b60 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
28b70 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
28b80 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
28b90 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
28ba0 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
28bb0 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
28bc0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
28bd0 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
28be0 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
28bf0 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
28c00 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
28c10 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
28c20 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
28c30 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
28c40 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
28c50 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
28c60 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
28c70 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
28c80 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
28c90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
28ca0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
28cb0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
28cc0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
28cd0 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
28ce0 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
28cf0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
28d00 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
28d10 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
28d20 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
28d30 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
28d40 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
28d50 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
28d60 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
28d70 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
28d80 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
28d90 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
28da0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
28db0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
28dc0 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
28dd0 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
28de0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
28df0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
28e00 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
28e10 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
28e20 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
28e30 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
28e40 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
28e50 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
28e60 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
28e70 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74   Every SQL funct
28e80 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
28e90 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20  on must be able 
28ea0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20  to work.** with 
28eb0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
28ec0 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
28ed0 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
28ee0 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
28ef0 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
28f00 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
28f10 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
28f20 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
28f30 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
28f40 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
28f50 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
28f60 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
28f70 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
28f80 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
28f90 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
28fa0 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
28fb0 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
28fc0 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65  TextRep..** ^Whe
28fd0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
28fe0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
28ff0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
29000 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
29010 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
29020 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
29030 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
29040 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
29050 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
29060 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
29070 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
29080 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
29090 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
290a0 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
290b0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
290c0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
290d0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
290e0 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
290f0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
29100 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
29110 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
29120 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
29130 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
29140 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
29150 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
29160 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
29170 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
29180 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
29190 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
291a0 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
291b0 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
291c0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
291d0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
291e0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
291f0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
29200 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
29210 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
29220 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
29230 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
29240 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
29250 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
29260 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
29270 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
29280 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
29290 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
292a0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
292b0 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
292c0 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
292d0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
292e0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
292f0 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
29300 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
29310 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
29320 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
29330 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
29340 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
29350 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
29360 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
29370 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
29380 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
29390 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
293a0 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
293b0 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
293c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
293d0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
293e0 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
293f0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
29400 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
29410 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
29420 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
29430 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
29440 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
29450 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
29460 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
29470 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
29480 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
29490 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
294a0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
294b0 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
294c0 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
294d0 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
294e0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
294f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
29500 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
29510 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
29520 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
29530 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
29540 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
29550 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
29560 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
29570 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
29580 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
29590 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
295a0 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
295b0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
295c0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
295d0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
295e0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
295f0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
29600 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
29610 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
29620 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
29630 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
29640 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
29650 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
29660 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
29670 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
29680 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
29690 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
296a0 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
296b0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
296c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
296d0 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
296e0 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
296f0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
29700 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
29710 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
29720 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
29730 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
29740 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
29750 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
29760 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
29770 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
29780 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
29790 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
297a0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
297b0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
297c0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
297d0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
297e0 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
297f0 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
29800 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
29810 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
29820 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
29830 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
29840 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
29850 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
29860 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
29870 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
29880 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
29890 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
298a0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
298b0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
298c0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
298d0 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
298e0 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
298f0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
29900 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
29910 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
29920 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
29930 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
29940 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
29950 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
29960 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
29970 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
29980 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
29990 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
299a0 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
299b0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
299c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
299d0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
299e0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
299f0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
29a00 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
29a10 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
29a20 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
29a30 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
29a40 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
29a50 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
29a60 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
29a70 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
29a80 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
29a90 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
29aa0 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
29ab0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29ac0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
29ad0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
29ae0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
29af0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
29b00 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
29b10 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
29b20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
29b30 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
29b40 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
29b50 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
29b60 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
29b70 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
29b80 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
29b90 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
29ba0 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
29bb0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
29bc0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
29bd0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
29be0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
29bf0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
29c00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
29c10 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
29c20 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
29c30 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
29c40 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  ext*).);.SQLITE_
29c50 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
29c60 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
29c70 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
29c80 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
29c90 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
29ca0 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
29cb0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
29cc0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
29cd0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
29ce0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
29cf0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
29d00 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
29d10 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
29d20 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
29d30 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
29d40 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
29d50 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f  _context*),.  vo
29d60 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
29d70 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
29d80 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
29d90 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
29da0 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
29db0 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
29dc0 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
29dd0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
29de0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
29df0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
29e00 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
29e10 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
29e20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
29e30 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
29e40 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
29e50 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
29e60 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
29e70 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
29e80 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
29e90 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
29ea0 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
29eb0 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
29ec0 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
29ed0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
29ee0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
29ef0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
29f00 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
29f10 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
29f20 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
29f30 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
29f40 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
29f50 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
29f60 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
29f70 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
29f80 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
29f90 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
29fa0 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
29fb0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
29fc0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
29fd0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
29fe0 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
29ff0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
2a000 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
2a010 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2a020 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
2a030 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
2a040 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
2a050 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
2a060 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
2a070 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
2a080 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
2a090 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
2a0a0 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
2a0b0 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
2a0c0 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
2a0d0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
2a0e0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
2a0f0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2a100 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
2a110 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
2a120 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
2a130 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2a140 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
2a150 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
2a160 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
2a170 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
2a180 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
2a190 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2a1a0 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
2a1b0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
2a1c0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
2a1d0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2a1e0 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
2a1f0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
2a200 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
2a210 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
2a220 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
2a230 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
2a240 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
2a250 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
2a260 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
2a270 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
2a280 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69  3_int64,int),voi
2a290 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
2a2a0 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
2a2b0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
2a2c0 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
2a2d0 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
2a2e0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
2a2f0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
2a300 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
2a310 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
2a320 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
2a330 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
2a340 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
2a350 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
2a360 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
2a370 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
2a380 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
2a390 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
2a3a0 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
2a3b0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
2a3c0 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
2a3d0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
2a3e0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2a3f0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
2a400 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2a410 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
2a420 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
2a430 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
2a440 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2a450 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
2a460 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
2a470 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
2a480 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
2a490 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
2a4a0 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
2a4b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2a4c0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
2a4d0 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
2a4e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2a4f0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
2a500 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
2a510 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
2a520 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2a530 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
2a540 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
2a550 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
2a560 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
2a570 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2a580 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
2a590 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
2a5a0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2a5b0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
2a5c0 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
2a5d0 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
2a5e0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2a5f0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
2a600 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
2a610 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
2a620 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
2a630 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
2a640 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
2a650 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
2a660 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2a670 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
2a680 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
2a690 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
2a6a0 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2a6b0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2a6c0 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
2a6d0 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
2a6e0 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
2a6f0 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
2a700 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
2a710 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a720 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
2a730 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
2a740 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
2a750 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
2a760 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
2a770 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
2a780 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
2a790 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2a7a0 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
2a7b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2a7c0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
2a7d0 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
2a7e0 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
2a7f0 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
2a800 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
2a810 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
2a820 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
2a830 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
2a840 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
2a850 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
2a860 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
2a870 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
2a880 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
2a890 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
2a8a0 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
2a8b0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
2a8c0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
2a8d0 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
2a8e0 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
2a8f0 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
2a900 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
2a910 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
2a920 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
2a930 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
2a940 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
2a950 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
2a960 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
2a970 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
2a980 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
2a990 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
2a9a0 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
2a9b0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2a9c0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
2a9d0 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
2a9e0 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
2a9f0 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
2aa00 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
2aa10 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
2aa20 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
2aa30 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
2aa40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2aa50 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
2aa60 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
2aa70 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2aa80 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
2aa90 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
2aaa0 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
2aab0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
2aac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2aad0 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
2aae0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
2aaf0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2ab00 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2ab10 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2ab20 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
2ab30 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
2ab40 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
2ab50 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
2ab60 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
2ab70 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
2ab80 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
2ab90 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
2aba0 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49  ameters..*/.SQLI
2abb0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2abc0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2abd0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
2abe0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
2abf0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
2ac00 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
2ac10 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2ac20 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2ac30 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2ac40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2ac50 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62  .SQLITE_API doub
2ac60 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
2ac70 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
2ac80 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2ac90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2aca0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
2acb0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2acc0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
2acd0 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
2ace0 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
2acf0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2ad00 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
2ad10 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2ad20 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
2ad30 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
2ad40 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2ad50 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
2ad60 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
2ad70 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2ad80 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2ad90 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
2ada0 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
2adb0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
2adc0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2add0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2ade0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
2adf0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2ae00 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
2ae10 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
2ae20 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
2ae30 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2ae40 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
2ae50 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
2ae60 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
2ae70 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
2ae80 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
2ae90 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
2aea0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2aeb0 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
2aec0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
2aed0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
2aee0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
2aef0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
2af00 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
2af10 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
2af20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
2af30 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2af40 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
2af50 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
2af60 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
2af70 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
2af80 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
2af90 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
2afa0 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
2afb0 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
2afc0 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
2afd0 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
2afe0 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
2aff0 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
2b000 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2b010 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2b020 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
2b030 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2b040 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
2b050 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
2b060 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
2b070 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
2b080 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
2b090 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
2b0a0 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
2b0b0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
2b0c0 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
2b0d0 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
2b0e0 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
2b0f0 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
2b100 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
2b110 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
2b120 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
2b130 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
2b140 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
2b150 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
2b160 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
2b170 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
2b180 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
2b190 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
2b1a0 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
2b1b0 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
2b1c0 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
2b1d0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2b1e0 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
2b1f0 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
2b200 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
2b210 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
2b220 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b230 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2b240 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
2b250 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
2b260 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73   pointer if N is
2b270 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  .** less than or
2b280 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
2b290 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
2b2a0 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
2b2b0 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
2b2c0 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
2b2d0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
2b2e0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2b2f0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
2b300 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
2b310 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
2b320 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
2b330 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
2b340 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
2b350 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
2b360 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
2b370 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2b380 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
2b390 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
2b3a0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
2b3b0 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
2b3c0 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
2b3d0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
2b3e0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2b3f0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
2b400 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
2b410 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
2b420 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
2b430 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
2b440 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
2b450 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
2b460 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
2b470 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
2b480 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
2b490 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
2b4a0 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
2b4b0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
2b4c0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
2b4d0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
2b4e0 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
2b4f0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
2b500 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
2b510 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
2b520 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
2b530 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
2b540 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
2b550 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
2b560 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
2b570 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
2b580 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
2b590 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
2b5a0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
2b5b0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2b5c0 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
2b5d0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
2b5e0 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
2b5f0 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
2b600 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
2b610 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b620 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
2b630 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2b640 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
2b650 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
2b660 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
2b670 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
2b680 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
2b690 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
2b6a0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2b6b0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
2b6c0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b6d0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
2b6e0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
2b6f0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
2b700 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2b710 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
2b720 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
2b730 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
2b740 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
2b750 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
2b760 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
2b770 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2b780 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2b790 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
2b7a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75   void *sqlite3_u
2b7b0 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
2b7c0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
2b7d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
2b7e0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2b7f0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
2b800 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2b810 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
2b820 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
2b830 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
2b840 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
2b850 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
2b860 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
2b870 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
2b880 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
2b890 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b8a0 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
2b8b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2b8c0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
2b8d0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
2b8e0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
2b8f0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
2b900 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
2b910 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
2b920 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c  API sqlite3 *sql
2b930 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2b940 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
2b950 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
2b960 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
2b970 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
2b980 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  ta.**.** The fol
2b990 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
2b9a0 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
2b9b0 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66   by scalar SQL f
2b9c0 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
2b9d0 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
2b9e0 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
2b9f0 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
2ba00 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
2ba10 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
2ba20 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
2ba30 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
2ba40 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
2ba50 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
2ba60 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
2ba70 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
2ba80 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
2ba90 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
2baa0 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a  rved. This may.*
2bab0 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  * be used, for e
2bac0 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61  xample, to add a
2bad0 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
2bae0 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61  ion matching sca
2baf0 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  lar.** function.
2bb00 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
2bb10 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
2bb20 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
2bb30 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  is stored as.** 
2bb40 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
2bb50 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
2bb60 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
2bb70 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2bb80 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
2bb90 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
2bba0 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
2bbb0 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
2bbc0 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
2bbd0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
2bbe0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2bbf0 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
2bc00 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
2bc10 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
2bc20 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
2bc30 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
2bc40 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
2bc50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2bc60 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
2bc70 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2bc80 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
2bc90 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
2bca0 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
2bcb0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2bcc0 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
2bcd0 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
2bce0 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
2bcf0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
2bd00 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2bd10 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  . ^If no metadat
2bd20 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
2bd30 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
2bd40 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
2bd50 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
2bd60 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
2bd70 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
2bd80 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
2bd90 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
2bda0 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
2bdb0 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
2bdc0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2bdd0 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
2bde0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2bdf0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2be00 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
2be10 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
2be20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
2be30 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74  pointed to by it
2be40 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  s 3rd parameter 
2be50 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  as the metadata 
2be60 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
2be70 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
2be80 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2be90 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
2bea0 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
2beb0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
2bec0 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
2bed0 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
2bee0 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
2bef0 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
2bf00 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  yed..** ^If it i
2bf10 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
2bf20 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
2bf30 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
2bf40 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20   function given 
2bf50 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  by the 4th param
2bf60 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2bf70 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e  set_auxdata() on
2bf80 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61  .** the metadata
2bf90 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
2bfa0 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
2bfb0 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
2bfc0 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  es.** or when th
2bfd0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2bfe0 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68  completes, which
2bff0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
2c000 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
2c010 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74  s free to call t
2c020 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e  he destructor an
2c030 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20  d drop metadata 
2c040 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65  on any.** parame
2c050 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74  ter of any funct
2c060 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e  ion at any time.
2c070 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72    ^The only guar
2c080 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a  antee is that.**
2c090 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
2c0a0 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62  will be called b
2c0b0 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61  efore the metada
2c0c0 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a  ta is dropped..*
2c0d0 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69  *.** ^(In practi
2c0e0 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
2c0f0 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
2c100 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
2c110 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
2c120 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
2c130 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
2c140 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
2c150 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
2c160 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61  values and [para
2c170 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  meters].)^.**.**
2c180 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2c190 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2c1a0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2c1b0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2c1c0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2c1d0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
2c1e0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
2c1f0 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
2c200 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2c210 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53  text*, int N);.S
2c220 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
2c230 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2c240 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
2c250 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
2c260 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
2c270 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
2c280 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
2c290 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
2c2a0 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
2c2b0 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
2c2c0 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
2c2d0 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
2c2e0 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
2c2f0 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
2c300 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
2c310 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
2c320 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
2c330 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
2c340 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
2c350 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
2c360 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
2c370 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
2c380 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
2c390 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
2c3a0 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
2c3b0 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
2c3c0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
2c3d0 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
2c3e0 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
2c3f0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
2c400 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
2c410 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
2c420 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
2c430 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
2c440 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
2c450 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
2c460 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
2c470 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
2c480 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
2c490 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
2c4a0 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
2c4b0 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
2c4c0 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
2c4d0 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
2c4e0 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  s.  See ticket #
2c4f0 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  2191..*/.typedef
2c500 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
2c510 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2c520 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
2c530 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
2c540 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
2c550 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
2c560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2c570 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
2c580 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
2c590 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
2c5a0 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
2c5b0 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
2c5c0 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
2c5d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2c5e0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
2c5f0 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
2c600 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
2c610 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
2c620 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
2c630 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
2c640 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
2c650 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c660 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2c670 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2c680 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
2c690 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
2c6a0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
2c6b0 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
2c6c0 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
2c6d0 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
2c6e0 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
2c6f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
2c700 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
2c710 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
2c720 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
2c730 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
2c740 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
2c750 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
2c760 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
2c770 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2c780 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
2c790 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2c7a0 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
2c7b0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
2c7c0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
2c7d0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2c7e0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2c7f0 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
2c800 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
2c810 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
2c820 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2c830 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
2c840 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
2c850 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
2c860 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
2c870 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c880 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
2c890 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
2c8a0 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
2c8b0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
2c8c0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2c8d0 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
2c8e0 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
2c8f0 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
2c900 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
2c910 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
2c920 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
2c930 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
2c940 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2c950 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
2c960 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
2c970 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
2c980 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
2c990 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2c9a0 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
2c9b0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
2c9c0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
2c9d0 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
2c9e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2c9f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2ca00 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
2ca10 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
2ca20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
2ca30 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
2ca40 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
2ca50 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
2ca60 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ption..** ^SQLit
2ca70 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
2ca80 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
2ca90 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
2caa0 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
2cab0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
2cac0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2cad0 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
2cae0 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
2caf0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
2cb00 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65  ^SQLite interpre
2cb10 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
2cb20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
2cb30 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
2cb40 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
2cb50 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  F-8. ^SQLite.** 
2cb60 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
2cb70 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
2cb80 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2cb90 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
2cba0 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
2cbb0 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20  order.  ^If the 
2cbc0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
2cbd0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
2cbe0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
2cbf0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
2cc00 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
2cc10 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
2cc20 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
2cc30 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
2cc40 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
2cc50 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
2cc60 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
2cc70 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
2cc80 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
2cc90 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2cca0 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2ccb0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
2ccc0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
2ccd0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
2cce0 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
2ccf0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
2cd00 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
2cd10 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
2cd20 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
2cd30 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ge..** ^The sqli
2cd40 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2cd50 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
2cd60 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
2cd70 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
2cd80 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
2cd90 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
2cda0 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
2cdb0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
2cdc0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
2cdd0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
2cde0 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
2cdf0 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
2ce00 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
2ce10 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
2ce20 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  m..** ^The sqlit
2ce30 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
2ce40 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
2ce50 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
2ce60 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
2ce70 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
2ce80 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
2ce90 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
2cea0 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74  on.  ^By default
2ceb0 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
2cec0 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
2ced0 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75  ROR.  ^A subsequ
2cee0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
2cef0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2cf00 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2cf10 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2cf20 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
2cf30 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
2cf40 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e  E_ERROR..**.** ^
2cf50 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2cf60 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  lt_toobig() inte
2cf70 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
2cf80 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
2cf90 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
2cfa0 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
2cfb0 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f  g or BLOB is too
2cfc0 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
2cfd0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
2cfe0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 6f  qlite3_result_no
2cff0 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
2d000 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
2d010 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f 72 0a   throw an error.
2d020 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ** indicating th
2d030 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
2d040 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
2d050 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2d060 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
2d070 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
2d080 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
2d090 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
2d0a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2d0b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
2d0c0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
2d0d0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
2d0e0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
2d0f0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
2d100 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2d110 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
2d120 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
2d130 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
2d140 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
2d150 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
2d160 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
2d170 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
2d180 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
2d190 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
2d1a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
2d1b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
2d1c0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
2d1d0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
2d1e0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
2d1f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2d200 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2d210 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
2d220 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2d230 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
2d240 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
2d250 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
2d260 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
2d270 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
2d280 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
2d290 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
2d2a0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2d2b0 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
2d2c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2d2d0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
2d2e0 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
2d2f0 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
2d300 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
2d310 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
2d320 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
2d330 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
2d340 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
2d350 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
2d360 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61  y..** ^SQLite ta
2d370 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
2d380 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
2d390 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
2d3a0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2d3b0 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
2d3c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
2d3d0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49  nterfaces..** ^I
2d3e0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
2d3f0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
2d400 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
2d410 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
2d420 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
2d430 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
2d440 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
2d450 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
2d460 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
2d470 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
2d480 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
2d490 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
2d4a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2d4b0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2d4c0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
2d4d0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
2d4e0 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
2d4f0 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
2d500 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
2d510 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
2d520 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
2d530 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
2d540 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2d550 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
2d560 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
2d570 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2d580 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
2d590 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
2d5a0 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
2d5b0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
2d5c0 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
2d5d0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
2d5e0 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
2d5f0 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
2d600 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
2d610 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
2d620 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
2d630 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
2d640 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
2d650 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
2d660 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
2d670 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2d680 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
2d690 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
2d6a0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
2d6b0 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
2d6c0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
2d6d0 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
2d6e0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
2d6f0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
2d700 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
2d710 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
2d720 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
2d730 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
2d740 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
2d750 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
2d760 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
2d770 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
2d780 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
2d790 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
2d7a0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
2d7b0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
2d7c0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
2d7d0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
2d7e0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
2d7f0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
2d800 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
2d810 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
2d820 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
2d830 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
2d840 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
2d850 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
2d860 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
2d870 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
2d880 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
2d890 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
2d8a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2d8b0 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
2d8c0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
2d8d0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
2d8e0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
2d8f0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
2d900 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
2d910 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2d920 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
2d930 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
2d940 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
2d950 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
2d960 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
2d970 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
2d980 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
2d990 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
2d9a0 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
2d9b0 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
2d9c0 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
2d9d0 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
2d9e0 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
2d9f0 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
2da00 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2da10 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
2da20 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
2da30 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2da40 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2da50 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
2da60 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
2da70 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2da80 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2da90 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
2daa0 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
2dab0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
2dac0 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
2dad0 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
2dae0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2daf0 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
2db00 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
2db10 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
2db20 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
2db30 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
2db40 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
2db50 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2db60 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
2db70 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
2db80 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
2db90 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
2dba0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2dbb0 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
2dbc0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
2dbd0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
2dbe0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2dbf0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2dc00 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2dc10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
2dc20 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
2dc30 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
2dc40 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
2dc50 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  e);.SQLITE_API v
2dc60 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2dc70 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
2dc80 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
2dc90 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51   char*, int);.SQ
2dca0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
2dcb0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2dcc0 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
2dcd0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
2dce0 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
2dcf0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
2dd00 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
2dd10 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
2dd20 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
2dd30 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
2dd40 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
2dd50 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
2dd60 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
2dd70 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
2dd80 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
2dd90 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2dda0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
2ddb0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
2ddc0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
2ddd0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
2dde0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
2ddf0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2de00 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
2de10 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
2de20 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  e3_int64);.SQLIT
2de30 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
2de40 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
2de50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2de60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
2de70 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2de80 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
2de90 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
2dea0 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
2deb0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
2dec0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
2ded0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2dee0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2def0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
2df00 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2df10 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
2df20 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
2df30 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
2df40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2df50 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
2df60 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
2df70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
2df80 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2df90 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2dfa0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
2dfb0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
2dfc0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
2dfd0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
2dfe0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2dff0 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
2e000 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
2e010 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
2e020 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
2e030 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
2e040 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
2e050 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
2e060 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
2e070 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
2e080 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  quences.**.** ^T
2e090 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
2e0a0 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d  dd, remove, or m
2e0b0 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69  odify a [collati
2e0c0 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  on] associated.*
2e0d0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
2e0e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e0f0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
2e100 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2e110 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2e120 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  e of the collati
2e130 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  on is a UTF-8 st
2e140 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
2e150 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2e160 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
2e170 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
2e180 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
2e190 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
2e1a0 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
2e1b0 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
2e1c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
2e1d0 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  n16()..** ^Colla
2e1e0 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20  tion names that 
2e1f0 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63  compare equal ac
2e200 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69  cording to [sqli
2e210 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20  te3_strnicmp()] 
2e220 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
2e230 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65  d to be the same
2e240 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   name..**.** ^(T
2e250 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
2e260 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73  t (eTextRep) mus
2e270 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
2e280 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75  constants:.** <u
2e290 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
2e2a0 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69  TE_UTF8],.** <li
2e2b0 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  > [SQLITE_UTF16L
2e2c0 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
2e2d0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
2e2e0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
2e2f0 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  F16], or.** <li>
2e300 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
2e310 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LIGNED]..** </ul
2e320 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78  >)^.** ^The eTex
2e330 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65  tRep argument de
2e340 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63  termines the enc
2e350 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73  oding of strings
2e360 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68   passed.** to th
2e370 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2e380 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78  tion callback, x
2e390 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  Callback..** ^Th
2e3a0 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
2e3b0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46   and [SQLITE_UTF
2e3c0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
2e3d0 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a  es for eTextRep.
2e3e0 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73  ** force strings
2e3f0 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74   to be UTF16 wit
2e400 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  h native byte or
2e410 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  der..** ^The [SQ
2e420 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
2e430 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54  ED] value for eT
2e440 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74  extRep forces st
2e450 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a  rings to begin.*
2e460 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74  * on an even byt
2e470 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a  e address..**.**
2e480 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67   ^The fourth arg
2e490 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20  ument, pArg, is 
2e4a0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
2e4b0 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
2e4c0 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
2e4d0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
2e4e0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
2e4f0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
2e500 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
2e510 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
2e520 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
2e530 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
2e540 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
2e550 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
2e560 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
2e570 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
2e580 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
2e590 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
2e5a0 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
2e5b0 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
2e5c0 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
2e5d0 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
2e5e0 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
2e5f0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2e600 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
2e610 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
2e620 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
2e630 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
2e640 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
2e650 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
2e660 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
2e670 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
2e680 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
2e690 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
2e6a0 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
2e6b0 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
2e6c0 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
2e6d0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
2e6e0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
2e6f0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2e700 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
2e710 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
2e720 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
2e730 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
2e740 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
2e750 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
2e760 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
2e770 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
2e780 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
2e790 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
2e7a0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
2e7b0 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a  ust return an.**
2e7c0 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
2e7d0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c   negative, zero,
2e7e0 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20   or positive.** 
2e7f0 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
2e800 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
2e810 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
2e820 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
2e830 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65  second,.** respe
2e840 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c  ctively.  A coll
2e850 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
2e860 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72  ust always retur
2e870 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65  n the same answe
2e880 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73  r.** given the s
2e890 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20  ame inputs.  If 
2e8a0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c  two or more coll
2e8b0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
2e8c0 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a  are registered.*
2e8d0 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f  * to the same co
2e8e0 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73  llation name (us
2e8f0 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54  ing different eT
2e900 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74  extRep values) t
2e910 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20  hen all.** must 
2e920 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65  give an equivale
2e930 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69  nt answer when i
2e940 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69  nvoked with equi
2e950 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a  valent strings..
2e960 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** The collating
2e970 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f   function must o
2e980 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  bey the followin
2e990 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72  g properties for
2e9a0 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20   all.** strings 
2e9b0 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a  A, B, and C:.**.
2e9c0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
2e9d0 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d  If A==B then B==
2e9e0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  A..** <li> If A=
2e9f0 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e  =B and B==C then
2ea00 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   A==C..** <li> I
2ea10 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26  f A&lt;B THEN B&
2ea20 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  gt;A..** <li> If
2ea30 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74   A&lt;B and B&lt
2ea40 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a  ;C then A&lt;C..
2ea50 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
2ea60 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  f a collating fu
2ea70 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79  nction fails any
2ea80 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f   of the above co
2ea90 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
2eaa0 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20  at.** collating 
2eab0 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67  function is  reg
2eac0 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64  istered and used
2ead0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2eae0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
2eaf0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2eb00 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2eb10 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2eb20 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
2eb30 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
2eb40 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
2eb50 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69   with the additi
2eb60 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73  on that the xDes
2eb70 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
2eb80 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67   invoked on pArg
2eb90 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c   when.** the col
2eba0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2ebb0 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  is deleted..** ^
2ebc0 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  Collating functi
2ebd0 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ons are deleted 
2ebe0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
2ebf0 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
2ec00 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68  r.** calls to th
2ec10 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
2ec20 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
2ec30 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64  r when the.** [d
2ec40 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2ec50 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73  on] is closed us
2ec60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
2ec70 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  se()]..**.** ^Th
2ec80 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
2ec90 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75  ack is <u>not</u
2eca0 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20  > called if the 
2ecb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
2ecc0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
2ecd0 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  ) function fails
2ece0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
2ecf0 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  that invoke.** s
2ed00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2ed10 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74  llation_v2() wit
2ed20 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65  h a non-NULL xDe
2ed30 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73  stroy argument s
2ed40 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20  hould .** check 
2ed50 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
2ed60 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74  and dispose of t
2ed70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2ed80 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ata pointer.** t
2ed90 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72  hemselves rather
2eda0 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20   than expecting 
2edb0 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77  SQLite to deal w
2edc0 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e  ith it for them.
2edd0 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66  .** This is diff
2ede0 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79  erent from every
2edf0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
2ee00 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e  terface.  The in
2ee10 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20  consistency .** 
2ee20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62  is unfortunate b
2ee30 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  ut cannot be cha
2ee40 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  nged without bre
2ee50 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20  aking backwards 
2ee60 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
2ee70 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  y..**.** See als
2ee80 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  o:  [sqlite3_col
2ee90 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
2eea0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
2eeb0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
2eec0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2eed0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2eee0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
2eef0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
2ef00 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2ef10 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
2ef20 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
2ef30 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
2ef40 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
2ef50 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
2ef60 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51  nst void*).);.SQ
2ef70 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2ef80 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2ef90 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
2efa0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
2efb0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
2efc0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
2efd0 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
2efe0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
2eff0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2f000 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
2f010 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
2f020 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
2f030 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f040 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
2f050 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
2f060 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
2f070 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
2f080 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
2f090 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
2f0a0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
2f0b0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2f0c0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
2f0d0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
2f0e0 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
2f0f0 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
2f100 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76  cks.**.** ^To av
2f110 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65  oid having to re
2f120 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61  gister all colla
2f130 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62  tion sequences b
2f140 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65  efore a database
2f150 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
2f160 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
2f170 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
2f180 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  be registered wi
2f190 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  th the.** [datab
2f1a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2f1b0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
2f1c0 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
2f1d0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
2f1e0 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
2f1f0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uired..**.** ^If
2f200 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
2f210 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
2f220 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
2f230 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
2f240 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74   API,.** then it
2f250 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e   is passed the n
2f260 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65  ames of undefine
2f270 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
2f280 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73  ences as strings
2f290 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55  .** encoded in U
2f2a0 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65  TF-8. ^If sqlite
2f2b0 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
2f2c0 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a  ed16() is used,.
2f2d0 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65  ** the names are
2f2e0 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
2f2f0 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
2f300 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
2f310 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69  ** ^A call to ei
2f320 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65  ther function re
2f330 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74  places the exist
2f340 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65  ing collation-ne
2f350 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  eded callback..*
2f360 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20  *.** ^(When the 
2f370 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
2f380 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
2f390 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
2f3a0 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
2f3b0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2f3c0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
2f3d0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
2f3e0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
2f3f0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
2f400 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
2f410 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2f420 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2f430 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68  nection.  The th
2f440 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
2f450 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
2f460 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
2f470 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  F16BE],.** or [S
2f480 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
2f490 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
2f4a0 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
2f4b0 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
2f4c0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
2f4d0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
2f4e0 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  d.  The fourth p
2f4f0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
2f500 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
2f510 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
2f520 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a  n sequence.)^.**
2f530 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
2f540 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
2f550 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65   register the de
2f560 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  sired collation 
2f570 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
2f580 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2f590 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
2f5a0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
2f5b0 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
2f5c0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2f5d0 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  lation_v2()]..*/
2f5e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f5f0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
2f600 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
2f610 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
2f620 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
2f630 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
2f640 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
2f650 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  r*).);.SQLITE_AP
2f660 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
2f670 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
2f680 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
2f690 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
2f6a0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
2f6b0 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
2f6c0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23  nst void*).);..#
2f6d0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53  ifdef SQLITE_HAS
2f6e0 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65  _CODEC./*.** Spe
2f6f0 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
2f700 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
2f710 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
2f720 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
2f730 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
2f740 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
2f750 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
2f760 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
2f770 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
2f780 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
2f790 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
2f7a0 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
2f7b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2f7c0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
2f7d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2f7e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2f7f0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
2f800 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
2f810 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
2f820 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
2f830 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
2f840 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
2f850 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
2f860 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
2f870 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
2f880 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
2f890 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
2f8a0 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
2f8b0 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
2f8c0 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
2f8d0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
2f8e0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
2f8f0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
2f900 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
2f910 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
2f920 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
2f930 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
2f940 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  Lite..*/.SQLITE_
2f950 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2f960 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
2f970 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
2f980 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2f990 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
2f9a0 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
2f9b0 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
2f9c0 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
2f9d0 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
2f9e0 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
2f9f0 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
2fa00 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e   a SEE database.
2fa10 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
2fa20 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
2fa30 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73  the SEE routines
2fa40 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53   will work..*/.S
2fa50 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
2fa60 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
2fa70 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
2fa80 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
2fa90 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
2faa0 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
2fab0 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
2fac0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
2fad0 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
2fae0 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
2faf0 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
2fb00 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
2fb10 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
2fb20 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
2fb30 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
2fb40 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  l work..*/.SQLIT
2fb50 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
2fb60 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f  e3_activate_cero
2fb70 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  d(.  const char 
2fb80 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
2fb90 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
2fba0 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
2fbb0 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2fbc0 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
2fbd0 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
2fbe0 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20  hort Time.**.** 
2fbf0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
2fc00 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
2fc10 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
2fc20 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
2fc30 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
2fc40 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
2fc50 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
2fc60 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
2fc70 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
2fc80 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
2fc90 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
2fca0 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
2fcb0 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
2fcc0 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
2fcd0 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
2fce0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
2fcf0 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
2fd00 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
2fd10 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
2fd20 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
2fd30 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
2fd40 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
2fd50 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
2fd60 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
2fd70 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
2fd80 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d  **.** ^SQLite im
2fd90 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
2fda0 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
2fdb0 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
2fdc0 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
2fdd0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
2fde0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
2fdf0 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20  If the xSleep() 
2fe00 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
2fe10 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
2fe20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
2fe30 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f  correctly, or no
2fe40 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74  t implemented at
2fe50 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68  .** all, then th
2fe60 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
2fe70 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61  lite3_sleep() ma
2fe80 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74  y deviate from t
2fe90 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a  he description.*
2fea0 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  * in the previou
2feb0 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f  s paragraphs..*/
2fec0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2fed0 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e  sqlite3_sleep(in
2fee0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2fef0 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65  REF: Name Of The
2ff00 20 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20   Folder Holding 
2ff10 54 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a  Temporary Files.
2ff20 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20  **.** ^(If this 
2ff30 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20  global variable 
2ff40 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74  is made to point
2ff50 20 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69   to a string whi
2ff60 63 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  ch is.** the nam
2ff70 65 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61  e of a folder (a
2ff80 2e 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29  .k.a. directory)
2ff90 2c 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f  , then all tempo
2ffa0 72 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72  rary files.** cr
2ffb0 65 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20  eated by SQLite 
2ffc0 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
2ffd0 6c 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76  lt-in [sqlite3_v
2ffe0 66 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c  fs | VFS].** wil
2fff0 6c 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74  l be placed in t
30000 68 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e  hat directory.)^
30010 20 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61    ^If this varia
30020 62 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  ble.** is a NULL
30030 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
30040 51 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61  QLite performs a
30050 20 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61   search for an a
30060 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65  ppropriate.** te
30070 6d 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72  mporary file dir
30080 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74  ectory..**.** It
30090 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
300a0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
300b0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
300c0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
300d0 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
300e0 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
300f0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
30100 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
30110 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
30120 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
30130 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
30140 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
30150 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
30160 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
30170 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
30180 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
30190 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
301a0 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
301b0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
301c0 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
301d0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
301e0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
301f0 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
30200 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
30210 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
30220 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
30230 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74  r..**.** ^The [t
30240 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
30250 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
30260 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
30270 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
30280 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
30290 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
302a0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
302b0 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
302c0 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74  rmore,.** the [t
302d0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
302e0 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
302f0 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
30300 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
30310 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
30320 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
30330 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
30340 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
30350 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
30360 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
30370 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
30380 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
30390 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
303a0 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
303b0 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
303c0 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
303d0 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
303e0 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
303f0 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
30400 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
30410 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
30420 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
30430 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
30440 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74  he use of the [t
30450 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
30460 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
30470 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
30480 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  /.SQLITE_API SQL
30490 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
304a0 2a 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69  *sqlite3_temp_di
304b0 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
304c0 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
304d0 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
304e0 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ode.** KEYWORDS:
304f0 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   {autocommit mod
30500 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e}.**.** ^The sq
30510 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
30520 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
30530 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
30540 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
30550 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
30560 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
30570 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
30580 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
30590 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
305a0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
305b0 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
305c0 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  lt..** ^Autocomm
305d0 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
305e0 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
305f0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
30600 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
30610 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79  is re-enabled by
30620 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
30630 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
30640 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
30650 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
30660 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
30670 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
30680 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
30690 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73  nsaction (errors
306a0 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49   including [SQLI
306b0 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_FULL], [SQLIT
306c0 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51  E_IOERR],.** [SQ
306d0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
306e0 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
306f0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
30700 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
30710 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
30720 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
30730 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
30740 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
30750 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65  .** find out whe
30760 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f  ther SQLite auto
30770 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
30780 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
30790 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
307a0 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
307b0 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
307c0 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
307d0 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
307e0 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
307f0 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
30800 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
30810 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
30820 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
30830 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
30840 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  urn value.** is 
30850 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51  undefined..*/.SQ
30860 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
30870 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
30880 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
30890 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
308a0 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
308b0 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
308c0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
308d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
308e0 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
308f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
30900 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
30910 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
30920 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
30930 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30940 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54  nt] belongs.  ^T
30950 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
30960 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75  nection].** retu
30970 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
30980 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65  db_handle is the
30990 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
309a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
309b0 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
309c0 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
309d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
309e0 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
309f0 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
30a00 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
30a10 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
30a20 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
30a30 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
30a40 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
30a50 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
30a60 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
30a70 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
30a80 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64 20 74  CAPI3REF: Find t
30a90 68 65 20 6e 65 78 74 20 70 72 65 70 61 72 65 64  he next prepared
30aa0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   statement.**.**
30ab0 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
30ac0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
30ad0 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74 20 5b  er to the next [
30ae0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
30af0 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70 53 74  nt] after.** pSt
30b00 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  mt associated wi
30b10 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
30b20 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 44 62   connection] pDb
30b30 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69 73 20  .  ^If pStmt is 
30b40 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74 68 69  NULL.** then thi
30b50 73 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  s interface retu
30b60 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
30b70 20 74 68 65 20 66 69 72 73 74 20 70 72 65 70 61   the first prepa
30b80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
30b90 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
30ba0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
30bb0 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20 20 5e  nnection pDb.  ^
30bc0 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64 20 73  If no prepared s
30bd0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61 74 69  tatement.** sati
30be0 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64 69 74  sfies the condit
30bf0 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72 6f 75  ions of this rou
30c00 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72 6e 73  tine, it returns
30c10 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
30c20 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30c30 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72 20 44  ction] pointer D
30c40 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a   in a call to.**
30c50 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
30c60 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74 20 72  tmt(D,S)] must r
30c70 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65 6e 20  efer to an open 
30c80 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
30c90 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20 70 61  ection and in pa
30ca0 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20 6e 6f  rticular must no
30cb0 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t be a NULL poin
30cc0 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ter..*/.SQLITE_A
30cd0 50 49 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  PI sqlite3_stmt 
30ce0 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  *sqlite3_next_st
30cf0 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44 62 2c  mt(sqlite3 *pDb,
30d00 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70   sqlite3_stmt *p
30d10 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
30d20 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41  PI3REF: Commit A
30d30 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69  nd Rollback Noti
30d40 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  fication Callbac
30d50 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
30d60 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
30d70 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  k() interface re
30d80 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61  gisters a callba
30d90 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74  ck.** function t
30da0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
30db0 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74  never a transact
30dc0 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c  ion is [COMMIT |
30dd0 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20   committed]..** 
30de0 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
30df0 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
30e00 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
30e10 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a  commit_hook().**
30e20 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
30e30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30e40 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
30e50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30e60 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
30e70 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
30e80 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
30e90 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
30ea0 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
30eb0 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
30ec0 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20   is [ROLLBACK | 
30ed0 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a  rolled back]..**
30ee0 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
30ef0 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
30f00 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
30f10 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
30f20 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65  .** for the same
30f30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
30f40 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64  tion is overridd
30f50 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67  en..** ^The pArg
30f60 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70 61 73   argument is pas
30f70 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74  sed through to t
30f80 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  he callback..** 
30f90 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
30fa0 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f   on a commit hoo
30fb0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  k function retur
30fc0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20  ns non-zero,.** 
30fd0 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20  then the commit 
30fe0 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74  is converted int
30ff0 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a  o a rollback..**
31000 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31010 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43  _commit_hook(D,C
31020 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ,P) and sqlite3_
31030 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c  rollback_hook(D,
31040 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  C,P) functions.*
31050 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50 20 61  * return the P a
31060 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65  rgument from the
31070 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f   previous call o
31080 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
31090 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61  ion.** on the sa
310a0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
310b0 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e  nection] D, or N
310c0 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66  ULL for.** the f
310d0 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20 65 61  irst call for ea
310e0 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44  ch function on D
310f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ..**.** The call
31100 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74  back implementat
31110 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ion must not do 
31120 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
31130 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
31140 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
31150 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
31160 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20  d the callback. 
31170 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20   Any actions.** 
31180 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  to modify the da
31190 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
311a0 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72  n must be deferr
311b0 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74  ed until after t
311c0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e  he.** completion
311d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
311e0 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68  _step()] call th
311f0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
31200 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f   commit.** or ro
31210 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74  llback hook in t
31220 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
31230 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
31240 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
31250 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
31260 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
31270 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
31280 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
31290 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
312a0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
312b0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
312c0 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74 65  ..**.** ^Registe
312d0 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e 63  ring a NULL func
312e0 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74 68  tion disables th
312f0 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a  e callback..**.*
31300 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d 6d  * ^When the comm
31310 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b  it hook callback
31320 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
31330 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d   zero, the [COMM
31340 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f 6e  IT].** operation
31350 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20 63   is allowed to c
31360 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79  ontinue normally
31370 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d 69  .  ^If the commi
31380 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e  t hook.** return
31390 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
313a0 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69 73   the [COMMIT] is
313b0 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20   converted into 
313c0 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  a [ROLLBACK]..**
313d0 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 68   ^The rollback h
313e0 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ook is invoked o
313f0 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68 61  n a rollback tha
31400 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 61  t results from a
31410 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20   commit.** hook 
31420 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65  returning non-ze
31430 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20 77  ro, just as it w
31440 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e 79  ould be with any
31450 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b 2e   other rollback.
31460 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
31470 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
31480 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63 74   API, a transact
31490 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20 68  ion is said to h
314a0 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c  ave been.** roll
314b0 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65 78  ed back if an ex
314c0 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43 4b  plicit "ROLLBACK
314d0 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 65  " statement is e
314e0 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20 61  xecuted, or.** a
314f0 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73 74  n error or const
31500 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e 20  raint causes an 
31510 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61 63  implicit rollbac
31520 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e  k to occur..** ^
31530 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61 6c  The rollback cal
31540 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e 76  lback is not inv
31550 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73 61  oked if a transa
31560 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74 6f  ction is.** auto
31570 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
31580 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74 68   back because th
31590 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
315a0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
315b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
315c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70 64  the [sqlite3_upd
315d0 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74 65  ate_hook()] inte
315e0 72 66 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  rface..*/.SQLITE
315f0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
31600 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73  e3_commit_hook(s
31610 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
31620 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
31630 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
31640 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63  *sqlite3_rollbac
31650 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a 2c  k_hook(sqlite3*,
31660 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a 29   void(*)(void *)
31670 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
31680 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 20   CAPI3REF: Data 
31690 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61 74  Change Notificat
316a0 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ion Callbacks.**
316b0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
316c0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20 69  _update_hook() i
316d0 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
316e0 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
316f0 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
31700 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
31710 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69 66  nection] identif
31720 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
31730 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
31740 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
31750 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70 64  ver a row is upd
31760 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
31770 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 41  r deleted..** ^A
31780 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
31790 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
317a0 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74  ll to this funct
317b0 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73  ion.** for the s
317c0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
317d0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72  nection is overr
317e0 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  idden..**.** ^Th
317f0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
31800 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
31810 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 74  o the function t
31820 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61 0a  o invoke when a.
31830 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74 65  ** row is update
31840 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  d, inserted or d
31850 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  eleted..** ^The 
31860 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
31870 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
31880 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
31890 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a  third argument.*
318a0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70 64  * to sqlite3_upd
318b0 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20 5e  ate_hook()..** ^
318c0 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c 62  The second callb
318d0 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
318e0 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49  one of [SQLITE_I
318f0 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  NSERT], [SQLITE_
31900 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  DELETE],.** or [
31910 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c 20  SQLITE_UPDATE], 
31920 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
31930 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
31940 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c 62  caused the callb
31950 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 76  ack.** to be inv
31960 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74 68  oked..** ^The th
31970 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 61  ird and fourth a
31980 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65 20  rguments to the 
31990 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
319a0 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65   pointers to the
319b0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e 64  .** database and
319c0 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f 6e 74   table name cont
319d0 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66 65 63  aining the affec
319e0 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54 68 65  ted row..** ^The
319f0 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20   final callback 
31a00 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
31a10 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
31a20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  row..** ^In the 
31a30 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64 61 74  case of an updat
31a40 65 2c 20 74 68 69 73 20 69 73 20 74 68 65 20 5b  e, this is the [
31a50 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74 68 65  rowid] after the
31a60 20 75 70 64 61 74 65 20 74 61 6b 65 73 20 70 6c   update takes pl
31a70 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ace..**.** ^(The
31a80 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 73 20   update hook is 
31a90 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
31aa0 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74 65 6d   internal system
31ab0 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a 20 6d   tables are.** m
31ac0 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20 73 71  odified (i.e. sq
31ad0 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e 64 20  lite_master and 
31ae0 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63 65 29  sqlite_sequence)
31af0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  .)^.**.** ^In th
31b00 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
31b10 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20 75 70  entation, the up
31b20 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 73 20  date hook.** is 
31b30 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e  not invoked when
31b40 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72 6f 77   duplication row
31b50 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 62 65  s are deleted be
31b60 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a 20 5b  cause of an.** [
31b70 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20 4f 4e  ON CONFLICT | ON
31b80 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c 41 43   CONFLICT REPLAC
31b90 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e 6f 72  E] clause.  ^Nor
31ba0 20 69 73 20 74 68 65 20 75 70 64 61 74 65 20 68   is the update h
31bb0 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 77  ook.** invoked w
31bc0 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c  hen rows are del
31bd0 65 74 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  eted using the [
31be0 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
31bf0 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65 20 65  ation]..** The e
31c00 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69 6e 65  xceptions define
31c10 64 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  d in this paragr
31c20 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e 67 65  aph might change
31c30 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
31c40 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
31c50 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75 70 64  e..**.** The upd
31c60 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65 6d 65  ate hook impleme
31c70 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ntation must not
31c80 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
31c90 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
31ca0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
31cb0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
31cc0 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61 74 65  voked the update
31cd0 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63 74 69   hook.  Any acti
31ce0 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66 79  ons.** to modify
31cf0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
31d00 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62 65  nnection must be
31d10 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
31d20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f 6d  after the.** com
31d30 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20 5b  pletion of the [
31d40 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
31d50 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
31d60 72 65 64 20 74 68 65 20 75 70 64 61 74 65 20 68  red the update h
31d70 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ook..** Note tha
31d80 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
31d90 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
31da0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
31db0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
31dc0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
31dd0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
31de0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
31df0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
31e00 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  graph..**.** ^Th
31e10 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65  e sqlite3_update
31e20 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e  _hook(D,C,P) fun
31e30 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72 6e 73  ction.** returns
31e40 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20   the P argument 
31e50 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
31e60 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74 68 65  s call.** on the
31e70 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
31e80 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f  connection] D, o
31e90 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68  r NULL for.** th
31ea0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f 6e 20  e first call on 
31eb0 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  D..**.** See als
31ec0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
31ed0 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20 61 6e  ommit_hook()] an
31ee0 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d [sqlite3_rollb
31ef0 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a 20 69  ack_hook()].** i
31f00 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a 53 51  nterfaces..*/.SQ
31f10 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
31f20 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
31f30 6f 6b 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20  ok(.  sqlite3*, 
31f40 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  .  void(*)(void 
31f50 2a 2c 69 6e 74 20 2c 63 68 61 72 20 63 6f 6e 73  *,int ,char cons
31f60 74 20 2a 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a  t *,char const *
31f70 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 2c  ,sqlite3_int64),
31f80 0a 20 20 76 6f 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a  .  void*.);../*.
31f90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61  ** CAPI3REF: Ena
31fa0 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 53  ble Or Disable S
31fb0 68 61 72 65 64 20 50 61 67 65 72 20 43 61 63 68  hared Pager Cach
31fc0 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  e.** KEYWORDS: {
31fd0 73 68 61 72 65 64 20 63 61 63 68 65 7d 0a 2a 2a  shared cache}.**
31fe0 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69  .** ^(This routi
31ff0 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
32000 73 61 62 6c 65 73 20 74 68 65 20 73 68 61 72 69  sables the shari
32010 6e 67 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ng of the databa
32020 73 65 20 63 61 63 68 65 0a 2a 2a 20 61 6e 64 20  se cache.** and 
32030 73 63 68 65 6d 61 20 64 61 74 61 20 73 74 72 75  schema data stru
32040 63 74 75 72 65 73 20 62 65 74 77 65 65 6e 20 5b  ctures between [
32050 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32060 69 6f 6e 20 7c 20 63 6f 6e 6e 65 63 74 69 6f 6e  ion | connection
32070 73 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  s].** to the sam
32080 65 20 64 61 74 61 62 61 73 65 2e 20 53 68 61 72  e database. Shar
32090 69 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 69  ing is enabled i
320a0 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
320b0 73 20 74 72 75 65 0a 2a 2a 20 61 6e 64 20 64 69  s true.** and di
320c0 73 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  sabled if the ar
320d0 67 75 6d 65 6e 74 20 69 73 20 66 61 6c 73 65 2e  gument is false.
320e0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 43 61 63 68 65 20  )^.**.** ^Cache 
320f0 73 68 61 72 69 6e 67 20 69 73 20 65 6e 61 62 6c  sharing is enabl
32100 65 64 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20  ed and disabled 
32110 66 6f 72 20 61 6e 20 65 6e 74 69 72 65 20 70 72  for an entire pr
32120 6f 63 65 73 73 2e 0a 2a 2a 20 54 68 69 73 20 69  ocess..** This i
32130 73 20 61 20 63 68 61 6e 67 65 20 61 73 20 6f 66  s a change as of
32140 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
32150 33 2e 35 2e 30 2e 20 49 6e 20 70 72 69 6f 72 20  3.5.0. In prior 
32160 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
32170 74 65 2c 0a 2a 2a 20 73 68 61 72 69 6e 67 20 77  te,.** sharing w
32180 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  as enabled or di
32190 73 61 62 6c 65 64 20 66 6f 72 20 65 61 63 68 20  sabled for each 
321a0 74 68 72 65 61 64 20 73 65 70 61 72 61 74 65 6c  thread separatel
321b0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 63  y..**.** ^(The c
321c0 61 63 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64  ache sharing mod
321d0 65 20 73 65 74 20 62 79 20 74 68 69 73 20 69 6e  e set by this in
321e0 74 65 72 66 61 63 65 20 65 66 66 65 63 74 73 20  terface effects 
321f0 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 0a 2a  all subsequent.*
32200 2a 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  * calls to [sqli
32210 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
32220 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
32230 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 6f  , and [sqlite3_o
32240 70 65 6e 31 36 28 29 5d 2e 0a 2a 2a 20 45 78 69  pen16()]..** Exi
32250 73 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 63  sting database c
32260 6f 6e 6e 65 63 74 69 6f 6e 73 20 63 6f 6e 74 69  onnections conti
32270 6e 75 65 20 75 73 65 20 74 68 65 20 73 68 61 72  nue use the shar
32280 69 6e 67 20 6d 6f 64 65 0a 2a 2a 20 74 68 61 74  ing mode.** that
32290 20 77 61 73 20 69 6e 20 65 66 66 65 63 74 20 61   was in effect a
322a0 74 20 74 68 65 20 74 69 6d 65 20 74 68 65 79 20  t the time they 
322b0 77 65 72 65 20 6f 70 65 6e 65 64 2e 29 5e 0a 2a  were opened.)^.*
322c0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
322d0 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
322e0 49 54 45 5f 4f 4b 5d 20 69 66 20 73 68 61 72 65  ITE_OK] if share
322f0 64 20 63 61 63 68 65 20 77 61 73 20 65 6e 61 62  d cache was enab
32300 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 0a  led or disabled.
32310 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
32320 20 20 41 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65    An [error code
32330 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 6f 74  ] is returned ot
32340 68 65 72 77 69 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a  herwise.)^.**.**
32350 20 5e 53 68 61 72 65 64 20 63 61 63 68 65 20 69   ^Shared cache i
32360 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  s disabled by de
32370 66 61 75 6c 74 2e 20 42 75 74 20 74 68 69 73 20  fault. But this 
32380 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e 0a  might change in.
32390 2a 2a 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ** future releas
323a0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  es of SQLite.  A
323b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
323c0 20 63 61 72 65 20 61 62 6f 75 74 20 73 68 61 72   care about shar
323d0 65 64 0a 2a 2a 20 63 61 63 68 65 20 73 65 74 74  ed.** cache sett
323e0 69 6e 67 20 73 68 6f 75 6c 64 20 73 65 74 20 69  ing should set i
323f0 74 20 65 78 70 6c 69 63 69 74 6c 79 2e 0a 2a 2a  t explicitly..**
32400 0a 2a 2a 20 53 65 65 20 41 6c 73 6f 3a 20 20 5b  .** See Also:  [
32410 53 51 4c 69 74 65 20 53 68 61 72 65 64 2d 43 61  SQLite Shared-Ca
32420 63 68 65 20 4d 6f 64 65 5d 0a 2a 2f 0a 53 51 4c  che Mode].*/.SQL
32430 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
32440 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
32450 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
32460 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
32470 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
32480 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
32490 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
324a0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
324b0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
324c0 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
324d0 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
324e0 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
324f0 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
32500 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
32510 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
32520 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
32530 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75  rary.   Memory u
32540 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
32550 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
32560 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
32570 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
32580 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
32590 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
325a0 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  ^sqlite3_release
325b0 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
325c0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
325d0 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
325e0 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
325f0 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
32600 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
32610 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
32620 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32630 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
32640 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f   routine is a no
32650 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65  -op returning ze
32660 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  ro.** if SQLite 
32670 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20  is not compiled 
32680 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41  with [SQLITE_ENA
32690 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
326a0 45 4d 45 4e 54 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  EMENT]..*/.SQLIT
326b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
326c0 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79  3_release_memory
326d0 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  (int);../*.** CA
326e0 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20 41  PI3REF: Impose A
326f0 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20 53   Limit On Heap S
32700 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ize.**.** ^The s
32710 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
32720 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e 74 65 72  _limit64() inter
32730 66 61 63 65 20 73 65 74 73 20 61 6e 64 2f 6f 72  face sets and/or
32740 20 71 75 65 72 69 65 73 20 74 68 65 0a 2a 2a 20   queries the.** 
32750 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e 20 74 68  soft limit on th
32760 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61 70  e amount of heap
32770 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61 79   memory that may
32780 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79   be allocated by
32790 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53 51 4c   SQLite..** ^SQL
327a0 69 74 65 20 73 74 72 69 76 65 73 20 74 6f 20 6b  ite strives to k
327b0 65 65 70 20 68 65 61 70 20 6d 65 6d 6f 72 79 20  eep heap memory 
327c0 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62 65 6c 6f  utilization belo
327d0 77 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 0a  w the soft heap.
327e0 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72 65 64 75  ** limit by redu
327f0 63 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72 20  cing the number 
32800 6f 66 20 70 61 67 65 73 20 68 65 6c 64 20 69 6e  of pages held in
32810 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 0a   the page cache.
32820 2a 2a 20 61 73 20 68 65 61 70 20 6d 65 6d 6f 72  ** as heap memor
32830 79 20 75 73 61 67 65 73 20 61 70 70 72 6f 61 63  y usages approac
32840 68 65 73 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a  hes the limit..*
32850 2a 20 5e 54 68 65 20 73 6f 66 74 20 68 65 61 70  * ^The soft heap
32860 20 6c 69 6d 69 74 20 69 73 20 22 73 6f 66 74 22   limit is "soft"
32870 20 62 65 63 61 75 73 65 20 65 76 65 6e 20 74 68   because even th
32880 6f 75 67 68 20 53 51 4c 69 74 65 20 73 74 72 69  ough SQLite stri
32890 76 65 73 20 74 6f 20 73 74 61 79 0a 2a 2a 20 62  ves to stay.** b
328a0 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69 74 2c 20  elow the limit, 
328b0 69 74 20 77 69 6c 6c 20 65 78 63 65 65 64 20 74  it will exceed t
328c0 68 65 20 6c 69 6d 69 74 20 72 61 74 68 65 72 20  he limit rather 
328d0 74 68 61 6e 20 67 65 6e 65 72 61 74 65 0a 2a 2a  than generate.**
328e0 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45   an [SQLITE_NOME
328f0 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e 20 6f 74  M] error.  In ot
32900 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 73  her words, the s
32910 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 0a  oft heap limit .
32920 2a 2a 20 69 73 20 61 64 76 69 73 6f 72 79 20 6f  ** is advisory o
32930 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nly..**.** ^The 
32940 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
32950 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68  m sqlite3_soft_h
32960 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 73  eap_limit64() is
32970 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a 20   the size of.** 
32980 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
32990 6d 69 74 20 70 72 69 6f 72 20 74 6f 20 74 68 65  mit prior to the
329a0 20 63 61 6c 6c 2e 20 20 5e 49 66 20 74 68 65 20   call.  ^If the 
329b0 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 6e 65  argument N is ne
329c0 67 61 74 69 76 65 0a 2a 2a 20 74 68 65 6e 20 6e  gative.** then n
329d0 6f 20 63 68 61 6e 67 65 20 69 73 20 6d 61 64 65  o change is made
329e0 20 74 6f 20 74 68 65 20 73 6f 66 74 20 68 65 61   to the soft hea
329f0 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e 63 65 2c  p limit.  Hence,
32a00 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
32a10 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f 66 74  size of the soft
32a20 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e 20   heap limit can 
32a30 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  be determined by
32a40 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c   invoking.** sql
32a50 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
32a60 69 6d 69 74 36 34 28 29 20 77 69 74 68 20 61 20  imit64() with a 
32a70 6e 65 67 61 74 69 76 65 20 61 72 67 75 6d 65 6e  negative argumen
32a80 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  t..**.** ^If the
32a90 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 7a   argument N is z
32aa0 65 72 6f 20 74 68 65 6e 20 74 68 65 20 73 6f 66  ero then the sof
32ab0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
32ac0 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
32ad0 5e 28 54 68 65 20 73 6f 66 74 20 68 65 61 70 20  ^(The soft heap 
32ae0 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 65 6e 66  limit is not enf
32af0 6f 72 63 65 64 20 69 6e 20 74 68 65 20 63 75 72  orced in the cur
32b00 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
32b10 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f 72  ion.** if one or
32b20 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f 77 69   more of followi
32b30 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73 20 61 72  ng conditions ar
32b40 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  e true:.**.** <u
32b50 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 73  l>.** <li> The s
32b60 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
32b70 73 20 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a 2a  s set to zero..*
32b80 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20 61 63  * <li> Memory ac
32b90 63 6f 75 6e 74 69 6e 67 20 69 73 20 64 69 73 61  counting is disa
32ba0 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 6f 6d  bled using a com
32bb0 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  bination of the.
32bc0 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33  **      [sqlite3
32bd0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
32be0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
32bf0 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74 2d 74 69  S],...) start-ti
32c00 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a 2a  me option and.**
32c10 20 20 20 20 20 20 74 68 65 20 5b 53 51 4c 49 54        the [SQLIT
32c20 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
32c30 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  TUS] compile-tim
32c40 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69  e option..** <li
32c50 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  > An alternative
32c60 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
32c70 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 73 70  ementation is sp
32c80 65 63 69 66 69 65 64 20 75 73 69 6e 67 0a 2a 2a  ecified using.**
32c90 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f 63        [sqlite3_c
32ca0 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
32cb0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 2c 2e 2e  ONFIG_PCACHE],..
32cc0 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  .)..** <li> The 
32cd0 70 61 67 65 20 63 61 63 68 65 20 61 6c 6c 6f 63  page cache alloc
32ce0 61 74 65 73 20 66 72 6f 6d 20 69 74 73 20 6f 77  ates from its ow
32cf0 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 73 75  n memory pool su
32d00 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20 20 20 62  pplied.**      b
32d10 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  y [sqlite3_confi
32d20 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
32d30 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 2e 2e 2e  G_PAGECACHE],...
32d40 29 20 72 61 74 68 65 72 20 74 68 61 6e 0a 2a 2a  ) rather than.**
32d50 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20 68        from the h
32d60 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  eap..** </ul>)^.
32d70 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67 20  **.** Beginning 
32d80 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72 73  with SQLite vers
32d90 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68 65 20 73  ion 3.7.3, the s
32da0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
32db0 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 72 65  s enforced.** re
32dc0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
32dd0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
32de0 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
32df0 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d  MORY_MANAGEMENT]
32e00 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
32e10 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b   option is invok
32e20 65 64 2e 20 20 57 69 74 68 20 5b 53 51 4c 49 54  ed.  With [SQLIT
32e30 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
32e40 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a 2a 20  MANAGEMENT],.** 
32e50 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  the soft heap li
32e60 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64 20  mit is enforced 
32e70 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f 72 79 20  on every memory 
32e80 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 57 69 74  allocation.  Wit
32e90 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  hout.** [SQLITE_
32ea0 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41  ENABLE_MEMORY_MA
32eb0 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68 65 20 73  NAGEMENT], the s
32ec0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
32ed0 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63 65 64 0a  s only enforced.
32ee0 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20 69  ** when memory i
32ef0 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 74  s allocated by t
32f00 68 65 20 70 61 67 65 20 63 61 63 68 65 2e 20 20  he page cache.  
32f10 54 65 73 74 69 6e 67 20 73 75 67 67 65 73 74 73  Testing suggests
32f20 20 74 68 61 74 20 62 65 63 61 75 73 65 0a 2a 2a   that because.**
32f30 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 20   the page cache 
32f40 69 73 20 74 68 65 20 70 72 65 64 6f 6d 69 6e 61  is the predomina
32f50 74 65 20 6d 65 6d 6f 72 79 20 75 73 65 72 20 69  te memory user i
32f60 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73 74 0a 2a  n SQLite, most.*
32f70 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77  * applications w
32f80 69 6c 6c 20 61 63 68 69 65 76 65 20 61 64 65 71  ill achieve adeq
32f90 75 61 74 65 20 73 6f 66 74 20 68 65 61 70 20 6c  uate soft heap l
32fa0 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d 65 6e 74  imit enforcement
32fb0 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74 68 65 20   without.** the 
32fc0 75 73 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 45  use of [SQLITE_E
32fd0 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e  NABLE_MEMORY_MAN
32fe0 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20  AGEMENT]..**.** 
32ff0 54 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  The circumstance
33000 73 20 75 6e 64 65 72 20 77 68 69 63 68 20 53 51  s under which SQ
33010 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66 6f 72 63  Lite will enforc
33020 65 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  e the soft heap 
33030 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20 63 68 61  limit may.** cha
33040 6e 67 65 73 20 69 6e 20 66 75 74 75 72 65 20 72  nges in future r
33050 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
33060 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
33070 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
33080 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
33090 5f 6c 69 6d 69 74 36 34 28 73 71 6c 69 74 65 33  _limit64(sqlite3
330a0 5f 69 6e 74 36 34 20 4e 29 3b 0a 0a 2f 2a 0a 2a  _int64 N);../*.*
330b0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
330c0 65 63 61 74 65 64 20 53 6f 66 74 20 48 65 61 70  ecated Soft Heap
330d0 20 4c 69 6d 69 74 20 49 6e 74 65 72 66 61 63 65   Limit Interface
330e0 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
330f0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 64  *.** This is a d
33100 65 70 72 65 63 61 74 65 64 20 76 65 72 73 69 6f  eprecated versio
33110 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  n of the [sqlite
33120 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
33130 74 36 34 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  t64()].** interf
33140 61 63 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ace.  This routi
33150 6e 65 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  ne is provided f
33160 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
33170 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 6f  mpatibility.** o
33180 6e 6c 79 2e 20 20 41 6c 6c 20 6e 65 77 20 61 70  nly.  All new ap
33190 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
331a0 64 20 75 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71  d use the.** [sq
331b0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
331c0 6c 69 6d 69 74 36 34 28 29 5d 20 69 6e 74 65 72  limit64()] inter
331d0 66 61 63 65 20 72 61 74 68 65 72 20 74 68 61 6e  face rather than
331e0 20 74 68 69 73 20 6f 6e 65 2e 0a 2a 2f 0a 53 51   this one..*/.SQ
331f0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
33200 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
33210 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
33220 70 5f 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a  p_limit(int N);.
33230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
33240 3a 20 45 78 74 72 61 63 74 20 4d 65 74 61 64 61  : Extract Metada
33250 74 61 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d  ta About A Colum
33260 6e 20 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a  n Of A Table.**.
33270 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
33280 20 72 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74   returns metadat
33290 61 20 61 62 6f 75 74 20 61 20 73 70 65 63 69 66  a about a specif
332a0 69 63 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73  ic column of a s
332b0 70 65 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62  pecific.** datab
332c0 61 73 65 20 74 61 62 6c 65 20 61 63 63 65 73 73  ase table access
332d0 69 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b  ible using the [
332e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
332f0 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70  ion] handle.** p
33300 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
33310 73 74 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  st function argu
33320 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
33330 20 63 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74   column is ident
33340 69 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63  ified by the sec
33350 6f 6e 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66  ond, third and f
33360 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 73  ourth parameters
33370 20 74 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63   to.** this func
33380 74 69 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e  tion. ^The secon
33390 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 65  d parameter is e
333a0 69 74 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f  ither the name o
333b0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  f the database.*
333c0 2a 20 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20  * (i.e. "main", 
333d0 22 74 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74  "temp", or an at
333e0 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 29  tached database)
333f0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
33400 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62  specified.** tab
33410 6c 65 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20  le or NULL. ^If 
33420 69 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  it is NULL, then
33430 20 61 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61   all attached da
33440 74 61 62 61 73 65 73 20 61 72 65 20 73 65 61 72  tabases are sear
33450 63 68 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ched.** for the 
33460 74 61 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20  table using the 
33470 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75  same algorithm u
33480 73 65 64 20 62 79 20 74 68 65 20 64 61 74 61 62  sed by the datab
33490 61 73 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a  ase engine to.**
334a0 20 72 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69   resolve unquali
334b0 66 69 65 64 20 74 61 62 6c 65 20 72 65 66 65 72  fied table refer
334c0 65 6e 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ences..**.** ^Th
334d0 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
334e0 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  th parameters to
334f0 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61   this function a
33500 72 65 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64  re the table and
33510 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20   column.** name 
33520 6f 66 20 74 68 65 20 64 65 73 69 72 65 64 20 63  of the desired c
33530 6f 6c 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76  olumn, respectiv
33540 65 6c 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20  ely. Neither of 
33550 74 68 65 73 65 20 70 61 72 61 6d 65 74 65 72 73  these parameters
33560 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e  .** may be NULL.
33570 0a 2a 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61  .**.** ^Metadata
33580 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   is returned by 
33590 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d  writing to the m
335a0 65 6d 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20  emory locations 
335b0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 35 74  passed as the 5t
335c0 68 0a 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75  h.** and subsequ
335d0 65 6e 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ent parameters t
335e0 6f 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  o this function.
335f0 20 5e 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61   ^Any of these a
33600 72 67 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a  rguments may be.
33610 2a 2a 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63  ** NULL, in whic
33620 68 20 63 61 73 65 20 74 68 65 20 63 6f 72 72 65  h case the corre
33630 73 70 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74  sponding element
33640 20 6f 66 20 6d 65 74 61 64 61 74 61 20 69 73 20   of metadata is 
33650 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  omitted..**.** ^
33660 28 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  (<blockquote>.**
33670 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22   <table border="
33680 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20  1">.** <tr><th> 
33690 50 61 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f  Parameter <th> O
336a0 75 74 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74  utput<br>Type <t
336b0 68 3e 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a  h>  Description.
336c0 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35  **.** <tr><td> 5
336d0 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68  th <td> const ch
336e0 61 72 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79  ar* <td> Data ty
336f0 70 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36  pe.** <tr><td> 6
33700 74 68 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68  th <td> const ch
33710 61 72 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66  ar* <td> Name of
33720 20 64 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69   default collati
33730 6f 6e 20 73 65 71 75 65 6e 63 65 0a 2a 2a 20 3c  on sequence.** <
33740 74 72 3e 3c 74 64 3e 20 37 74 68 20 3c 74 64 3e  tr><td> 7th <td>
33750 20 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64   int         <td
33760 3e 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e  > True if column
33770 20 68 61 73 20 61 20 4e 4f 54 20 4e 55 4c 4c 20   has a NOT NULL 
33780 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 3c 74  constraint.** <t
33790 72 3e 3c 74 64 3e 20 38 74 68 20 3c 74 64 3e 20  r><td> 8th <td> 
337a0 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
337b0 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
337c0 69 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 50  is part of the P
337d0 52 49 4d 41 52 59 20 4b 45 59 0a 2a 2a 20 3c 74  RIMARY KEY.** <t
337e0 72 3e 3c 74 64 3e 20 39 74 68 20 3c 74 64 3e 20  r><td> 9th <td> 
337f0 69 6e 74 20 20 20 20 20 20 20 20 20 3c 74 64 3e  int         <td>
33800 20 54 72 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20   True if column 
33810 69 73 20 5b 41 55 54 4f 49 4e 43 52 45 4d 45 4e  is [AUTOINCREMEN
33820 54 5d 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  T].** </table>.*
33830 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
33840 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ^.**.** ^The mem
33850 6f 72 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ory pointed to b
33860 79 20 74 68 65 20 63 68 61 72 61 63 74 65 72 20  y the character 
33870 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65  pointers returne
33880 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 64 65 63  d for the.** dec
33890 6c 61 72 61 74 69 6f 6e 20 74 79 70 65 20 61 6e  laration type an
338a0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
338b0 65 6e 63 65 20 69 73 20 76 61 6c 69 64 20 6f 6e  ence is valid on
338c0 6c 79 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  ly until the nex
338d0 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 61 6e 79  t.** call to any
338e0 20 53 51 4c 69 74 65 20 41 50 49 20 66 75 6e 63   SQLite API func
338f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tion..**.** ^If 
33900 74 68 65 20 73 70 65 63 69 66 69 65 64 20 74 61  the specified ta
33910 62 6c 65 20 69 73 20 61 63 74 75 61 6c 6c 79 20  ble is actually 
33920 61 20 76 69 65 77 2c 20 61 6e 20 5b 65 72 72 6f  a view, an [erro
33930 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
33940 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
33950 68 65 20 73 70 65 63 69 66 69 65 64 20 63 6f 6c  he specified col
33960 75 6d 6e 20 69 73 20 22 72 6f 77 69 64 22 2c 20  umn is "rowid", 
33970 22 6f 69 64 22 20 6f 72 20 22 5f 72 6f 77 69 64  "oid" or "_rowid
33980 5f 22 20 61 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e  _" and an.** [IN
33990 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
339a0 59 5d 20 63 6f 6c 75 6d 6e 20 68 61 73 20 62 65  Y] column has be
339b0 65 6e 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  en explicitly de
339c0 63 6c 61 72 65 64 2c 20 74 68 65 6e 20 74 68 65  clared, then the
339d0 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
339e0 65 74 65 72 73 20 61 72 65 20 73 65 74 20 66 6f  eters are set fo
339f0 72 20 74 68 65 20 65 78 70 6c 69 63 69 74 6c 79  r the explicitly
33a00 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
33a10 2e 20 5e 28 49 66 20 74 68 65 72 65 20 69 73 20  . ^(If there is 
33a20 6e 6f 0a 2a 2a 20 65 78 70 6c 69 63 69 74 6c 79  no.** explicitly
33a30 20 64 65 63 6c 61 72 65 64 20 5b 49 4e 54 45 47   declared [INTEG
33a40 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
33a50 63 6f 6c 75 6d 6e 2c 20 74 68 65 6e 20 74 68 65  column, then the
33a60 20 6f 75 74 70 75 74 0a 2a 2a 20 70 61 72 61 6d   output.** param
33a70 65 74 65 72 73 20 61 72 65 20 73 65 74 20 61 73  eters are set as
33a80 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
33a90 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 64 61 74  <pre>.**     dat
33aa0 61 20 74 79 70 65 3a 20 22 49 4e 54 45 47 45 52  a type: "INTEGER
33ab0 22 0a 2a 2a 20 20 20 20 20 63 6f 6c 6c 61 74 69  ".**     collati
33ac0 6f 6e 20 73 65 71 75 65 6e 63 65 3a 20 22 42 49  on sequence: "BI
33ad0 4e 41 52 59 22 0a 2a 2a 20 20 20 20 20 6e 6f 74  NARY".**     not
33ae0 20 6e 75 6c 6c 3a 20 30 0a 2a 2a 20 20 20 20 20   null: 0.**     
33af0 70 72 69 6d 61 72 79 20 6b 65 79 3a 20 31 0a 2a  primary key: 1.*
33b00 2a 20 20 20 20 20 61 75 74 6f 20 69 6e 63 72 65  *     auto incre
33b10 6d 65 6e 74 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65  ment: 0.** </pre
33b20 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  >)^.**.** ^(This
33b30 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6c 6f   function may lo
33b40 61 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 73  ad one or more s
33b50 63 68 65 6d 61 73 20 66 72 6f 6d 20 64 61 74 61  chemas from data
33b60 62 61 73 65 20 66 69 6c 65 73 2e 20 49 66 20 61  base files. If a
33b70 6e 0a 2a 2a 20 65 72 72 6f 72 20 6f 63 63 75 72  n.** error occur
33b80 73 20 64 75 72 69 6e 67 20 74 68 69 73 20 70 72  s during this pr
33b90 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 74 68 65  ocess, or if the
33ba0 20 72 65 71 75 65 73 74 65 64 20 74 61 62 6c 65   requested table
33bb0 20 6f 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61   or column.** ca
33bc0 6e 6e 6f 74 20 62 65 20 66 6f 75 6e 64 2c 20 61  nnot be found, a
33bd0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
33be0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 61  s returned and a
33bf0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
33c00 6c 65 66 74 0a 2a 2a 20 69 6e 20 74 68 65 20 5b  left.** in the [
33c10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33c20 69 6f 6e 5d 20 28 74 6f 20 62 65 20 72 65 74 72  ion] (to be retr
33c30 69 65 76 65 64 20 75 73 69 6e 67 20 73 71 6c 69  ieved using sqli
33c40 74 65 33 5f 65 72 72 6d 73 67 28 29 29 2e 29 5e  te3_errmsg()).)^
33c50 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 41 50 49  .**.** ^This API
33c60 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62   is only availab
33c70 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
33c80 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
33c90 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
33ca0 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
33cb0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
33cc0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
33cd0 20 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c   defined..*/.SQL
33ce0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
33cf0 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e  te3_table_column
33d00 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c  _metadata(.  sql
33d10 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
33d20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e           /* Conn
33d30 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f  ection handle */
33d40 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
33d50 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f  DbName,        /
33d60 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20  * Database name 
33d70 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e  or NULL */.  con
33d80 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e  st char *zTableN
33d90 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c  ame,     /* Tabl
33da0 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73  e name */.  cons
33db0 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e  t char *zColumnN
33dc0 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d  ame,    /* Colum
33dd0 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72  n name */.  char
33de0 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54   const **pzDataT
33df0 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55  ype,    /* OUTPU
33e00 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61  T: Declared data
33e10 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20   type */.  char 
33e20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65  const **pzCollSe
33e30 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  q,     /* OUTPUT
33e40 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  : Collation sequ
33e50 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69  ence name */.  i
33e60 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20  nt *pNotNull,   
33e70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
33e80 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f  TPUT: True if NO
33e90 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
33ea0 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e  t exists */.  in
33eb0 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20  t *pPrimaryKey, 
33ec0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
33ed0 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
33ee0 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a  umn part of PK *
33ef0 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e  /.  int *pAutoin
33f00 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  c               
33f10 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
33f20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74  if column is aut
33f30 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29  o-increment */.)
33f40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33f50 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  F: Load An Exten
33f60 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  sion.**.** ^This
33f70 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73   interface loads
33f80 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e   an SQLite exten
33f90 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f  sion library fro
33fa0 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65  m the named file
33fb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33fc0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
33fd0 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
33fe0 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64  attempts to load
33ff0 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78   an.** SQLite ex
34000 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
34010 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65  contained in the
34020 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a   file zFile..**.
34030 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79 20 70 6f  ** ^The entry po
34040 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a  int is zProc..**
34050 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30   ^zProc may be 0
34060 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
34070 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
34080 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64  entry point.** d
34090 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69  efaults to "sqli
340a0 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e  te3_extension_in
340b0 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  it"..** ^The sql
340c0 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
340d0 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
340e0 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
340f0 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
34100 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52  s and [SQLITE_ER
34110 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e  ROR] if somethin
34120 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
34130 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63   ^If an error oc
34140 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73  curs and pzErrMs
34150 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e  g is not 0, then
34160 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
34170 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
34180 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
34190 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a  ll attempt to.**
341a0 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20   fill *pzErrMsg 
341b0 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61  with error messa
341c0 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69  ge text stored i
341d0 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61  n memory.** obta
341e0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
341f0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68  e3_malloc()]. Th
34200 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
34210 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65  on.** should fre
34220 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79  e this memory by
34230 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
34240 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
34250 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64   ^Extension load
34260 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62  ing must be enab
34270 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  led using.** [sq
34280 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
34290 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70  d_extension()] p
342a0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
342b0 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68  this API,.** oth
342c0 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
342d0 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64  will be returned
342e0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
342f0 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e   the [load_exten
34300 73 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63 74  sion() SQL funct
34310 69 6f 6e 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ion]..*/.SQLITE_
34320 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34330 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 0a  load_extension(.
34340 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
34350 20 20 20 20 20 20 20 20 2f 2a 20 4c 6f 61 64 20          /* Load 
34360 74 68 65 20 65 78 74 65 6e 73 69 6f 6e 20 69 6e  the extension in
34370 74 6f 20 74 68 69 73 20 64 61 74 61 62 61 73 65  to this database
34380 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2a 2f 0a 20   connection */. 
34390 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69   const char *zFi
343a0 6c 65 2c 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f  le,    /* Name o
343b0 66 20 74 68 65 20 73 68 61 72 65 64 20 6c 69 62  f the shared lib
343c0 72 61 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20  rary containing 
343d0 65 78 74 65 6e 73 69 6f 6e 20 2a 2f 0a 20 20 63  extension */.  c
343e0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 72 6f 63  onst char *zProc
343f0 2c 20 20 20 20 2f 2a 20 45 6e 74 72 79 20 70 6f  ,    /* Entry po
34400 69 6e 74 2e 20 20 44 65 72 69 76 65 64 20 66 72  int.  Derived fr
34410 6f 6d 20 7a 46 69 6c 65 20 69 66 20 30 20 2a 2f  om zFile if 0 */
34420 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  .  char **pzErrM
34430 73 67 20 20 20 20 20 20 20 2f 2a 20 50 75 74 20  sg       /* Put 
34440 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 68 65  error message he
34450 72 65 20 69 66 20 6e 6f 74 20 30 20 2a 2f 0a 29  re if not 0 */.)
34460 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34470 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
34480 61 62 6c 65 20 45 78 74 65 6e 73 69 6f 6e 20 4c  able Extension L
34490 6f 61 64 69 6e 67 0a 2a 2a 0a 2a 2a 20 5e 53 6f  oading.**.** ^So
344a0 20 61 73 20 6e 6f 74 20 74 6f 20 6f 70 65 6e 20   as not to open 
344b0 73 65 63 75 72 69 74 79 20 68 6f 6c 65 73 20 69  security holes i
344c0 6e 20 6f 6c 64 65 72 20 61 70 70 6c 69 63 61 74  n older applicat
344d0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  ions that are.**
344e0 20 75 6e 70 72 65 70 61 72 65 64 20 74 6f 20 64   unprepared to d
344f0 65 61 6c 20 77 69 74 68 20 65 78 74 65 6e 73 69  eal with extensi
34500 6f 6e 20 6c 6f 61 64 69 6e 67 2c 20 61 6e 64 20  on loading, and 
34510 61 73 20 61 20 6d 65 61 6e 73 20 6f 66 20 64 69  as a means of di
34520 73 61 62 6c 69 6e 67 0a 2a 2a 20 65 78 74 65 6e  sabling.** exten
34530 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 77 68 69  sion loading whi
34540 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 75 73  le evaluating us
34550 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 2c 20  er-entered SQL, 
34560 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 41 50  the following AP
34570 49 0a 2a 2a 20 69 73 20 70 72 6f 76 69 64 65 64  I.** is provided
34580 20 74 6f 20 74 75 72 6e 20 74 68 65 20 5b 73 71   to turn the [sq
34590 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
345a0 73 69 6f 6e 28 29 5d 20 6d 65 63 68 61 6e 69 73  sion()] mechanis
345b0 6d 20 6f 6e 20 61 6e 64 20 6f 66 66 2e 0a 2a 2a  m on and off..**
345c0 0a 2a 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c  .** ^Extension l
345d0 6f 61 64 69 6e 67 20 69 73 20 6f 66 66 20 62 79  oading is off by
345e0 20 64 65 66 61 75 6c 74 2e 20 53 65 65 20 74 69   default. See ti
345f0 63 6b 65 74 20 23 31 38 36 33 2e 0a 2a 2a 20 5e  cket #1863..** ^
34600 43 61 6c 6c 20 74 68 65 20 73 71 6c 69 74 65 33  Call the sqlite3
34610 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
34620 65 6e 73 69 6f 6e 28 29 20 72 6f 75 74 69 6e 65  ension() routine
34630 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 31 0a 2a   with onoff==1.*
34640 2a 20 74 6f 20 74 75 72 6e 20 65 78 74 65 6e 73  * to turn extens
34650 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 6f 6e 20 61  ion loading on a
34660 6e 64 20 63 61 6c 6c 20 69 74 20 77 69 74 68 20  nd call it with 
34670 6f 6e 6f 66 66 3d 3d 30 20 74 6f 20 74 75 72 6e  onoff==0 to turn
34680 0a 2a 2a 20 69 74 20 62 61 63 6b 20 6f 66 66 20  .** it back off 
34690 61 67 61 69 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  again..*/.SQLITE
346a0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
346b0 5f 65 6e 61 62 6c 65 5f 6c 6f 61 64 5f 65 78 74  _enable_load_ext
346c0 65 6e 73 69 6f 6e 28 73 71 6c 69 74 65 33 20 2a  ension(sqlite3 *
346d0 64 62 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  db, int onoff);.
346e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
346f0 20 41 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 4c   Automatically L
34700 6f 61 64 20 53 74 61 74 69 63 61 6c 6c 79 20 4c  oad Statically L
34710 69 6e 6b 65 64 20 45 78 74 65 6e 73 69 6f 6e 73  inked Extensions
34720 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
34730 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68  erface causes th
34740 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  e xEntryPoint() 
34750 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
34760 6e 76 6f 6b 65 64 20 66 6f 72 0a 2a 2a 20 65 61  nvoked for.** ea
34770 63 68 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65  ch new [database
34780 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61   connection] tha
34790 74 20 69 73 20 63 72 65 61 74 65 64 2e 20 20 54  t is created.  T
347a0 68 65 20 69 64 65 61 20 68 65 72 65 20 69 73 20  he idea here is 
347b0 74 68 61 74 0a 2a 2a 20 78 45 6e 74 72 79 50 6f  that.** xEntryPo
347c0 69 6e 74 28 29 20 69 73 20 74 68 65 20 65 6e 74  int() is the ent
347d0 72 79 20 70 6f 69 6e 74 20 66 6f 72 20 61 20 73  ry point for a s
347e0 74 61 74 69 63 61 6c 6c 79 20 6c 69 6e 6b 65 64  tatically linked
347f0 20 53 51 4c 69 74 65 20 65 78 74 65 6e 73 69 6f   SQLite extensio
34800 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 74 6f 20  n.** that is to 
34810 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
34820 20 6c 6f 61 64 65 64 20 69 6e 74 6f 20 61 6c 6c   loaded into all
34830 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
34840 6e 6e 65 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  nnections..**.**
34850 20 5e 28 45 76 65 6e 20 74 68 6f 75 67 68 20 74   ^(Even though t
34860 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 72 6f 74  he function prot
34870 6f 74 79 70 65 20 73 68 6f 77 73 20 74 68 61 74  otype shows that
34880 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 74   xEntryPoint() t
34890 61 6b 65 73 0a 2a 2a 20 6e 6f 20 61 72 67 75 6d  akes.** no argum
348a0 65 6e 74 73 20 61 6e 64 20 72 65 74 75 72 6e 73  ents and returns
348b0 20 76 6f 69 64 2c 20 53 51 4c 69 74 65 20 69 6e   void, SQLite in
348c0 76 6f 6b 65 73 20 78 45 6e 74 72 79 50 6f 69 6e  vokes xEntryPoin
348d0 74 28 29 20 77 69 74 68 20 74 68 72 65 65 0a 2a  t() with three.*
348e0 2a 20 61 72 67 75 6d 65 6e 74 73 20 61 6e 64 20  * arguments and 
348f0 65 78 70 65 63 74 73 20 61 6e 64 20 69 6e 74 65  expects and inte
34900 67 65 72 20 72 65 73 75 6c 74 20 61 73 20 69 66  ger result as if
34910 20 74 68 65 20 73 69 67 6e 61 74 75 72 65 20 6f   the signature o
34920 66 20 74 68 65 0a 2a 2a 20 65 6e 74 72 79 20 70  f the.** entry p
34930 6f 69 6e 74 20 77 68 65 72 65 20 61 73 20 66 6f  oint where as fo
34940 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
34950 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
34960 2a 20 26 6e 62 73 70 3b 20 20 69 6e 74 20 78 45  * &nbsp;  int xE
34970 6e 74 72 79 50 6f 69 6e 74 28 0a 2a 2a 20 26 6e  ntryPoint(.** &n
34980 62 73 70 3b 20 20 20 20 73 71 6c 69 74 65 33 20  bsp;    sqlite3 
34990 2a 64 62 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  *db,.** &nbsp;  
349a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70    const char **p
349b0 7a 45 72 72 4d 73 67 2c 0a 2a 2a 20 26 6e 62 73  zErrMsg,.** &nbs
349c0 70 3b 20 20 20 20 63 6f 6e 73 74 20 73 74 72 75  p;    const stru
349d0 63 74 20 73 71 6c 69 74 65 33 5f 61 70 69 5f 72  ct sqlite3_api_r
349e0 6f 75 74 69 6e 65 73 20 2a 70 54 68 75 6e 6b 0a  outines *pThunk.
349f0 2a 2a 20 26 6e 62 73 70 3b 20 20 29 3b 0a 2a 2a  ** &nbsp;  );.**
34a00 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
34a10 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 49 66 20  ote>)^.**.** If 
34a20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74 20  the xEntryPoint 
34a30 72 6f 75 74 69 6e 65 20 65 6e 63 6f 75 6e 74 65  routine encounte
34a40 72 73 20 61 6e 20 65 72 72 6f 72 2c 20 69 74 20  rs an error, it 
34a50 73 68 6f 75 6c 64 20 6d 61 6b 65 20 2a 70 7a 45  should make *pzE
34a60 72 72 4d 73 67 0a 2a 2a 20 70 6f 69 6e 74 20 74  rrMsg.** point t
34a70 6f 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  o an appropriate
34a80 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 28   error message (
34a90 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
34aa0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
34ab0 5d 29 0a 2a 2a 20 61 6e 64 20 72 65 74 75 72 6e  ]).** and return
34ac0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
34ad0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 20 20 5e  [error code].  ^
34ae0 53 51 4c 69 74 65 20 65 6e 73 75 72 65 73 20 74  SQLite ensures t
34af0 68 61 74 20 2a 70 7a 45 72 72 4d 73 67 0a 2a 2a  hat *pzErrMsg.**
34b00 20 69 73 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20   is NULL before 
34b10 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 45 6e 74  calling the xEnt
34b20 72 79 50 6f 69 6e 74 28 29 2e 20 20 5e 53 51 4c  ryPoint().  ^SQL
34b30 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a  ite will invoke.
34b40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
34b50 28 29 5d 20 6f 6e 20 2a 70 7a 45 72 72 4d 73 67  ()] on *pzErrMsg
34b60 20 61 66 74 65 72 20 78 45 6e 74 72 79 50 6f 69   after xEntryPoi
34b70 6e 74 28 29 20 72 65 74 75 72 6e 73 2e 20 20 5e  nt() returns.  ^
34b80 49 66 20 61 6e 79 0a 2a 2a 20 78 45 6e 74 72 79  If any.** xEntry
34b90 50 6f 69 6e 74 28 29 20 72 65 74 75 72 6e 73 20  Point() returns 
34ba0 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 20 5b 73  an error, the [s
34bb0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
34bc0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
34bd0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
34be0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 63 61  e3_open_v2()] ca
34bf0 6c 6c 20 74 68 61 74 20 70 72 6f 76 6f 6b 65 64  ll that provoked
34c00 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e 74   the xEntryPoint
34c10 28 29 20 77 69 6c 6c 20 66 61 69 6c 2e 0a 2a 2a  () will fail..**
34c20 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
34c30 69 74 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73  ite3_auto_extens
34c40 69 6f 6e 28 58 29 20 77 69 74 68 20 61 6e 20 65  ion(X) with an e
34c50 6e 74 72 79 20 70 6f 69 6e 74 20 58 20 74 68 61  ntry point X tha
34c60 74 20 69 73 20 61 6c 72 65 61 64 79 0a 2a 2a 20  t is already.** 
34c70 6f 6e 20 74 68 65 20 6c 69 73 74 20 6f 66 20 61  on the list of a
34c80 75 74 6f 6d 61 74 69 63 20 65 78 74 65 6e 73 69  utomatic extensi
34c90 6f 6e 73 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ons is a harmles
34ca0 73 20 6e 6f 2d 6f 70 2e 20 5e 4e 6f 20 65 6e 74  s no-op. ^No ent
34cb0 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 77 69 6c 6c  ry point.** will
34cc0 20 62 65 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20   be called more 
34cd0 74 68 61 6e 20 6f 6e 63 65 20 66 6f 72 20 65 61  than once for ea
34ce0 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
34cf0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 73 20 6f  ection that is o
34d00 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  pened..**.** See
34d10 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
34d20 72 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e  reset_auto_exten
34d30 73 69 6f 6e 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  sion()]..*/.SQLI
34d40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
34d50 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
34d60 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50  n(void (*xEntryP
34d70 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f  oint)(void));../
34d80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
34d90 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
34da0 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
34db0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
34dc0 65 72 66 61 63 65 20 64 69 73 61 62 6c 65 73 20  erface disables 
34dd0 61 6c 6c 20 61 75 74 6f 6d 61 74 69 63 20 65 78  all automatic ex
34de0 74 65 6e 73 69 6f 6e 73 20 70 72 65 76 69 6f 75  tensions previou
34df0 73 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  sly.** registere
34e00 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
34e10 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
34e20 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
34e30 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
34e40 65 73 65 74 5f 61 75 74 6f 5f 65 78 74 65 6e 73  eset_auto_extens
34e50 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ion(void);../*.*
34e60 2a 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20  * The interface 
34e70 74 6f 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  to the virtual-t
34e80 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 69  able mechanism i
34e90 73 20 63 75 72 72 65 6e 74 6c 79 20 63 6f 6e 73  s currently cons
34ea0 69 64 65 72 65 64 0a 2a 2a 20 74 6f 20 62 65 20  idered.** to be 
34eb0 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 54  experimental.  T
34ec0 68 65 20 69 6e 74 65 72 66 61 63 65 20 6d 69 67  he interface mig
34ed0 68 74 20 63 68 61 6e 67 65 20 69 6e 20 69 6e 63  ht change in inc
34ee0 6f 6d 70 61 74 69 62 6c 65 20 77 61 79 73 2e 0a  ompatible ways..
34ef0 2a 2a 20 49 66 20 74 68 69 73 20 69 73 20 61 20  ** If this is a 
34f00 70 72 6f 62 6c 65 6d 20 66 6f 72 20 79 6f 75 2c  problem for you,
34f10 20 64 6f 20 6e 6f 74 20 75 73 65 20 74 68 65 20   do not use the 
34f20 69 6e 74 65 72 66 61 63 65 20 61 74 20 74 68 69  interface at thi
34f30 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  s time..**.** Wh
34f40 65 6e 20 74 68 65 20 76 69 72 74 75 61 6c 2d 74  en the virtual-t
34f50 61 62 6c 65 20 6d 65 63 68 61 6e 69 73 6d 20 73  able mechanism s
34f60 74 61 62 69 6c 69 7a 65 73 2c 20 77 65 20 77 69  tabilizes, we wi
34f70 6c 6c 20 64 65 63 6c 61 72 65 20 74 68 65 0a 2a  ll declare the.*
34f80 2a 20 69 6e 74 65 72 66 61 63 65 20 66 69 78 65  * interface fixe
34f90 64 2c 20 73 75 70 70 6f 72 74 20 69 74 20 69 6e  d, support it in
34fa0 64 65 66 69 6e 69 74 65 6c 79 2c 20 61 6e 64 20  definitely, and 
34fb0 72 65 6d 6f 76 65 20 74 68 69 73 20 63 6f 6d 6d  remove this comm
34fc0 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 53  ent..*/../*.** S
34fd0 74 72 75 63 74 75 72 65 73 20 75 73 65 64 20 62  tructures used b
34fe0 79 20 74 68 65 20 76 69 72 74 75 61 6c 20 74 61  y the virtual ta
34ff0 62 6c 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2f  ble interface.*/
35000 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
35010 73 71 6c 69 74 65 33 5f 76 74 61 62 20 73 71 6c  sqlite3_vtab sql
35020 69 74 65 33 5f 76 74 61 62 3b 0a 74 79 70 65 64  ite3_vtab;.typed
35030 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
35040 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 71 6c  3_index_info sql
35050 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 3b  ite3_index_info;
35060 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
35070 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
35080 73 6f 72 20 73 71 6c 69 74 65 33 5f 76 74 61 62  sor sqlite3_vtab
35090 5f 63 75 72 73 6f 72 3b 0a 74 79 70 65 64 65 66  _cursor;.typedef
350a0 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
350b0 6d 6f 64 75 6c 65 20 73 71 6c 69 74 65 33 5f 6d  module sqlite3_m
350c0 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  odule;../*.** CA
350d0 50 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20  PI3REF: Virtual 
350e0 54 61 62 6c 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Table Object.** 
350f0 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65  KEYWORDS: sqlite
35100 33 5f 6d 6f 64 75 6c 65 20 7b 76 69 72 74 75 61  3_module {virtua
35110 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 7d 0a  l table module}.
35120 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 74 72 75 63  **.** This struc
35130 74 75 72 65 2c 20 73 6f 6d 65 74 69 6d 65 73 20  ture, sometimes 
35140 63 61 6c 6c 65 64 20 61 20 22 76 69 72 74 75 61  called a "virtua
35150 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 22 2c  l table module",
35160 20 0a 2a 2a 20 64 65 66 69 6e 65 73 20 74 68 65   .** defines the
35170 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
35180 6f 66 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  of a [virtual ta
35190 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20 54 68 69 73  bles].  .** This
351a0 20 73 74 72 75 63 74 75 72 65 20 63 6f 6e 73 69   structure consi
351b0 73 74 73 20 6d 6f 73 74 6c 79 20 6f 66 20 6d 65  sts mostly of me
351c0 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f  thods for the mo
351d0 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 76  dule..**.** ^A v
351e0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
351f0 75 6c 65 20 69 73 20 63 72 65 61 74 65 64 20 62  ule is created b
35200 79 20 66 69 6c 6c 69 6e 67 20 69 6e 20 61 20 70  y filling in a p
35210 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 69 6e 73  ersistent.** ins
35220 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 73 74  tance of this st
35230 72 75 63 74 75 72 65 20 61 6e 64 20 70 61 73 73  ructure and pass
35240 69 6e 67 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ing a pointer to
35250 20 74 68 61 74 20 69 6e 73 74 61 6e 63 65 0a 2a   that instance.*
35260 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
35270 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 5d 20 6f  eate_module()] o
35280 72 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  r [sqlite3_creat
35290 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 5d 2e 0a  e_module_v2()]..
352a0 2a 2a 20 5e 54 68 65 20 72 65 67 69 73 74 72 61  ** ^The registra
352b0 74 69 6f 6e 20 72 65 6d 61 69 6e 73 20 76 61 6c  tion remains val
352c0 69 64 20 75 6e 74 69 6c 20 69 74 20 69 73 20 72  id until it is r
352d0 65 70 6c 61 63 65 64 20 62 79 20 61 20 64 69 66  eplaced by a dif
352e0 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f 64 75 6c 65  ferent.** module
352f0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 5b 64   or until the [d
35300 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
35310 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20 20 54 68 65  on] closes.  The
35320 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 6f 66 20 74   content.** of t
35330 68 69 73 20 73 74 72 75 63 74 75 72 65 20 6d 75  his structure mu
35340 73 74 20 6e 6f 74 20 63 68 61 6e 67 65 20 77 68  st not change wh
35350 69 6c 65 20 69 74 20 69 73 20 72 65 67 69 73 74  ile it is regist
35360 65 72 65 64 20 77 69 74 68 0a 2a 2a 20 61 6e 79  ered with.** any
35370 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
35380 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72 75 63 74 20  tion..*/.struct 
35390 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b  sqlite3_module {
353a0 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
353b0 0a 20 20 69 6e 74 20 28 2a 78 43 72 65 61 74 65  .  int (*xCreate
353c0 29 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64  )(sqlite3*, void
353d0 20 2a 70 41 75 78 2c 0a 20 20 20 20 20 20 20 20   *pAux,.        
353e0 20 20 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c         int argc,
353f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e   const char *con
35400 73 74 2a 61 72 67 76 2c 0a 20 20 20 20 20 20 20  st*argv,.       
35410 20 20 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f          sqlite3_
35420 76 74 61 62 20 2a 2a 70 70 56 54 61 62 2c 20 63  vtab **ppVTab, c
35430 68 61 72 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  har**);.  int (*
35440 78 43 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65  xConnect)(sqlite
35450 33 2a 2c 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a  3*, void *pAux,.
35460 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69                 i
35470 6e 74 20 61 72 67 63 2c 20 63 6f 6e 73 74 20 63  nt argc, const c
35480 68 61 72 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c  har *const*argv,
35490 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
354a0 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2a 70  sqlite3_vtab **p
354b0 70 56 54 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a  pVTab, char**);.
354c0 20 20 69 6e 74 20 28 2a 78 42 65 73 74 49 6e 64    int (*xBestInd
354d0 65 78 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ex)(sqlite3_vtab
354e0 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65 33   *pVTab, sqlite3
354f0 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a 29 3b 0a 20  _index_info*);. 
35500 20 69 6e 74 20 28 2a 78 44 69 73 63 6f 6e 6e 65   int (*xDisconne
35510 63 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  ct)(sqlite3_vtab
35520 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
35530 28 2a 78 44 65 73 74 72 6f 79 29 28 73 71 6c 69  (*xDestroy)(sqli
35540 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
35550 3b 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  ;.  int (*xOpen)
35560 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
35570 56 54 61 62 2c 20 73 71 6c 69 74 65 33 5f 76 74  VTab, sqlite3_vt
35580 61 62 5f 63 75 72 73 6f 72 20 2a 2a 70 70 43 75  ab_cursor **ppCu
35590 72 73 6f 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78  rsor);.  int (*x
355a0 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
355b0 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20  tab_cursor*);.  
355c0 69 6e 74 20 28 2a 78 46 69 6c 74 65 72 29 28 73  int (*xFilter)(s
355d0 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
355e0 6f 72 2a 2c 20 69 6e 74 20 69 64 78 4e 75 6d 2c  or*, int idxNum,
355f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 69 64 78   const char *idx
35600 53 74 72 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Str,.           
35610 20 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 73       int argc, s
35620 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 2a 61  qlite3_value **a
35630 72 67 76 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4e  rgv);.  int (*xN
35640 65 78 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ext)(sqlite3_vta
35650 62 5f 63 75 72 73 6f 72 2a 29 3b 0a 20 20 69 6e  b_cursor*);.  in
35660 74 20 28 2a 78 45 6f 66 29 28 73 71 6c 69 74 65  t (*xEof)(sqlite
35670 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
35680 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6c 75 6d 6e  .  int (*xColumn
35690 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63  )(sqlite3_vtab_c
356a0 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f  ursor*, sqlite3_
356b0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
356c0 20 20 69 6e 74 20 28 2a 78 52 6f 77 69 64 29 28    int (*xRowid)(
356d0 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
356e0 73 6f 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  sor*, sqlite3_in
356f0 74 36 34 20 2a 70 52 6f 77 69 64 29 3b 0a 20 20  t64 *pRowid);.  
35700 69 6e 74 20 28 2a 78 55 70 64 61 74 65 29 28 73  int (*xUpdate)(s
35710 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 2c 20 69  qlite3_vtab *, i
35720 6e 74 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nt, sqlite3_valu
35730 65 20 2a 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  e **, sqlite3_in
35740 74 36 34 20 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  t64 *);.  int (*
35750 78 42 65 67 69 6e 29 28 73 71 6c 69 74 65 33 5f  xBegin)(sqlite3_
35760 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
35770 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c  int (*xSync)(sql
35780 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
35790 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f 6d 6d  );.  int (*xComm
357a0 69 74 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  it)(sqlite3_vtab
357b0 20 2a 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20   *pVTab);.  int 
357c0 28 2a 78 52 6f 6c 6c 62 61 63 6b 29 28 73 71 6c  (*xRollback)(sql
357d0 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
357e0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6e 64  );.  int (*xFind
357f0 46 75 6e 63 74 69 6f 6e 29 28 73 71 6c 69 74 65  Function)(sqlite
35800 33 5f 76 74 61 62 20 2a 70 56 74 61 62 2c 20 69  3_vtab *pVtab, i
35810 6e 74 20 6e 41 72 67 2c 20 63 6f 6e 73 74 20 63  nt nArg, const c
35820 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a 20 20 20 20  har *zName,.    
35830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35840 20 20 20 76 6f 69 64 20 28 2a 2a 70 78 46 75 6e     void (**pxFun
35850 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
35860 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
35870 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 20 20 20 20  value**),.      
35880 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
35890 20 76 6f 69 64 20 2a 2a 70 70 41 72 67 29 3b 0a   void **ppArg);.
358a0 20 20 69 6e 74 20 28 2a 78 52 65 6e 61 6d 65 29    int (*xRename)
358b0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
358c0 56 74 61 62 2c 20 63 6f 6e 73 74 20 63 68 61 72  Vtab, const char
358d0 20 2a 7a 4e 65 77 29 3b 0a 7d 3b 0a 0a 2f 2a 0a   *zNew);.};../*.
358e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
358f0 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 64 65 78  tual Table Index
35900 69 6e 67 20 49 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ing Information.
35910 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c  ** KEYWORDS: sql
35920 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 0a  ite3_index_info.
35930 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
35940 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20 73 74 72  3_index_info str
35950 75 63 74 75 72 65 20 61 6e 64 20 69 74 73 20 73  ucture and its s
35960 75 62 73 74 72 75 63 74 75 72 65 73 20 69 73 20  ubstructures is 
35970 75 73 65 64 20 61 73 20 70 61 72 74 0a 2a 2a 20  used as part.** 
35980 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20  of the [virtual 
35990 74 61 62 6c 65 5d 20 69 6e 74 65 72 66 61 63 65  table] interface
359a0 20 74 6f 0a 2a 2a 20 70 61 73 73 20 69 6e 66 6f   to.** pass info
359b0 72 6d 61 74 69 6f 6e 20 69 6e 74 6f 20 61 6e 64  rmation into and
359c0 20 72 65 63 65 69 76 65 20 74 68 65 20 72 65 70   receive the rep
359d0 6c 79 20 66 72 6f 6d 20 74 68 65 20 5b 78 42 65  ly from the [xBe
359e0 73 74 49 6e 64 65 78 5d 0a 2a 2a 20 6d 65 74 68  stIndex].** meth
359f0 6f 64 20 6f 66 20 61 20 5b 76 69 72 74 75 61 6c  od of a [virtual
35a00 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20   table module]. 
35a10 20 54 68 65 20 66 69 65 6c 64 73 20 75 6e 64 65   The fields unde
35a20 72 20 2a 2a 49 6e 70 75 74 73 2a 2a 20 61 72 65  r **Inputs** are
35a30 20 74 68 65 0a 2a 2a 20 69 6e 70 75 74 73 20 74   the.** inputs t
35a40 6f 20 78 42 65 73 74 49 6e 64 65 78 20 61 6e 64  o xBestIndex and
35a50 20 61 72 65 20 72 65 61 64 2d 6f 6e 6c 79 2e 20   are read-only. 
35a60 20 78 42 65 73 74 49 6e 64 65 78 20 69 6e 73 65   xBestIndex inse
35a70 72 74 73 20 69 74 73 0a 2a 2a 20 72 65 73 75 6c  rts its.** resul
35a80 74 73 20 69 6e 74 6f 20 74 68 65 20 2a 2a 4f 75  ts into the **Ou
35a90 74 70 75 74 73 2a 2a 20 66 69 65 6c 64 73 2e 0a  tputs** fields..
35aa0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 43 6f 6e  **.** ^(The aCon
35ab0 73 74 72 61 69 6e 74 5b 5d 20 61 72 72 61 79 20  straint[] array 
35ac0 72 65 63 6f 72 64 73 20 57 48 45 52 45 20 63 6c  records WHERE cl
35ad0 61 75 73 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  ause constraints
35ae0 20 6f 66 20 74 68 65 20 66 6f 72 6d 3a 0a 2a 2a   of the form:.**
35af0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
35b00 63 6f 6c 75 6d 6e 20 4f 50 20 65 78 70 72 3c 2f  column OP expr</
35b10 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
35b20 2a 20 77 68 65 72 65 20 4f 50 20 69 73 20 3d 2c  * where OP is =,
35b30 20 26 6c 74 3b 2c 20 26 6c 74 3b 3d 2c 20 26 67   &lt;, &lt;=, &g
35b40 74 3b 2c 20 6f 72 20 26 67 74 3b 3d 2e 29 5e 20  t;, or &gt;=.)^ 
35b50 20 5e 28 54 68 65 20 70 61 72 74 69 63 75 6c 61   ^(The particula
35b60 72 20 6f 70 65 72 61 74 6f 72 20 69 73 0a 2a 2a  r operator is.**
35b70 20 73 74 6f 72 65 64 20 69 6e 20 61 43 6f 6e 73   stored in aCons
35b80 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 75 73 69 6e  traint[].op usin
35b90 67 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  g one of the.** 
35ba0 5b 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f  [SQLITE_INDEX_CO
35bb0 4e 53 54 52 41 49 4e 54 5f 45 51 20 7c 20 53 51  NSTRAINT_EQ | SQ
35bc0 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54  LITE_INDEX_CONST
35bd0 52 41 49 4e 54 5f 20 76 61 6c 75 65 73 5d 2e 29  RAINT_ values].)
35be0 5e 0a 2a 2a 20 5e 28 54 68 65 20 69 6e 64 65 78  ^.** ^(The index
35bf0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
35c00 73 20 73 74 6f 72 65 64 20 69 6e 0a 2a 2a 20 61  s stored in.** a
35c10 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 2e 69 43 6f  Constraint[].iCo
35c20 6c 75 6d 6e 2e 29 5e 20 20 5e 28 61 43 6f 6e 73  lumn.)^  ^(aCons
35c30 74 72 61 69 6e 74 5b 5d 2e 75 73 61 62 6c 65 20  traint[].usable 
35c40 69 73 20 54 52 55 45 20 69 66 20 74 68 65 0a 2a  is TRUE if the.*
35c50 2a 20 65 78 70 72 20 6f 6e 20 74 68 65 20 72 69  * expr on the ri
35c60 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 63 61  ght-hand side ca
35c70 6e 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 28  n be evaluated (
35c80 61 6e 64 20 74 68 75 73 20 74 68 65 20 63 6f 6e  and thus the con
35c90 73 74 72 61 69 6e 74 0a 2a 2a 20 69 73 20 75 73  straint.** is us
35ca0 61 62 6c 65 29 20 61 6e 64 20 66 61 6c 73 65 20  able) and false 
35cb0 69 66 20 69 74 20 63 61 6e 6e 6f 74 2e 29 5e 0a  if it cannot.)^.
35cc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 70 74 69 6d  **.** ^The optim
35cd0 69 7a 65 72 20 61 75 74 6f 6d 61 74 69 63 61 6c  izer automatical
35ce0 6c 79 20 69 6e 76 65 72 74 73 20 74 65 72 6d 73  ly inverts terms
35cf0 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 65 78   of the form "ex
35d00 70 72 20 4f 50 20 63 6f 6c 75 6d 6e 22 0a 2a 2a  pr OP column".**
35d10 20 61 6e 64 20 6d 61 6b 65 73 20 6f 74 68 65 72   and makes other
35d20 20 73 69 6d 70 6c 69 66 69 63 61 74 69 6f 6e 73   simplifications
35d30 20 74 6f 20 74 68 65 20 57 48 45 52 45 20 63 6c   to the WHERE cl
35d40 61 75 73 65 20 69 6e 20 61 6e 20 61 74 74 65 6d  ause in an attem
35d50 70 74 20 74 6f 0a 2a 2a 20 67 65 74 20 61 73 20  pt to.** get as 
35d60 6d 61 6e 79 20 57 48 45 52 45 20 63 6c 61 75 73  many WHERE claus
35d70 65 20 74 65 72 6d 73 20 69 6e 74 6f 20 74 68 65  e terms into the
35d80 20 66 6f 72 6d 20 73 68 6f 77 6e 20 61 62 6f 76   form shown abov
35d90 65 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 0a 2a  e as possible..*
35da0 2a 20 5e 54 68 65 20 61 43 6f 6e 73 74 72 61 69  * ^The aConstrai
35db0 6e 74 5b 5d 20 61 72 72 61 79 20 6f 6e 6c 79 20  nt[] array only 
35dc0 72 65 70 6f 72 74 73 20 57 48 45 52 45 20 63 6c  reports WHERE cl
35dd0 61 75 73 65 20 74 65 72 6d 73 20 74 68 61 74 20  ause terms that 
35de0 61 72 65 0a 2a 2a 20 72 65 6c 65 76 61 6e 74 20  are.** relevant 
35df0 74 6f 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  to the particula
35e00 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
35e10 62 65 69 6e 67 20 71 75 65 72 69 65 64 2e 0a 2a  being queried..*
35e20 2a 0a 2a 2a 20 5e 49 6e 66 6f 72 6d 61 74 69 6f  *.** ^Informatio
35e30 6e 20 61 62 6f 75 74 20 74 68 65 20 4f 52 44 45  n about the ORDE
35e40 52 20 42 59 20 63 6c 61 75 73 65 20 69 73 20 73  R BY clause is s
35e50 74 6f 72 65 64 20 69 6e 20 61 4f 72 64 65 72 42  tored in aOrderB
35e60 79 5b 5d 2e 0a 2a 2a 20 5e 45 61 63 68 20 74 65  y[]..** ^Each te
35e70 72 6d 20 6f 66 20 61 4f 72 64 65 72 42 79 20 72  rm of aOrderBy r
35e80 65 63 6f 72 64 73 20 61 20 63 6f 6c 75 6d 6e 20  ecords a column 
35e90 6f 66 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  of the ORDER BY 
35ea0 63 6c 61 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  clause..**.** Th
35eb0 65 20 5b 78 42 65 73 74 49 6e 64 65 78 5d 20 6d  e [xBestIndex] m
35ec0 65 74 68 6f 64 20 6d 75 73 74 20 66 69 6c 6c 20  ethod must fill 
35ed0 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61 67 65  aConstraintUsage
35ee0 5b 5d 20 77 69 74 68 20 69 6e 66 6f 72 6d 61 74  [] with informat
35ef0 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 77 68 61  ion.** about wha
35f00 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
35f10 70 61 73 73 20 74 6f 20 78 46 69 6c 74 65 72 2e  pass to xFilter.
35f20 20 20 5e 49 66 20 61 72 67 76 49 6e 64 65 78 3e    ^If argvIndex>
35f30 30 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 72 69  0 then.** the ri
35f40 67 68 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  ght-hand side of
35f50 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
35f60 6e 67 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d  ng aConstraint[]
35f70 20 69 73 20 65 76 61 6c 75 61 74 65 64 0a 2a 2a   is evaluated.**
35f80 20 61 6e 64 20 62 65 63 6f 6d 65 73 20 74 68 65   and becomes the
35f90 20 61 72 67 76 49 6e 64 65 78 2d 74 68 20 65 6e   argvIndex-th en
35fa0 74 72 79 20 69 6e 20 61 72 67 76 2e 20 20 5e 28  try in argv.  ^(
35fb0 49 66 20 61 43 6f 6e 73 74 72 61 69 6e 74 55 73  If aConstraintUs
35fc0 61 67 65 5b 5d 2e 6f 6d 69 74 0a 2a 2a 20 69 73  age[].omit.** is
35fd0 20 74 72 75 65 2c 20 74 68 65 6e 20 74 68 65 20   true, then the 
35fe0 63 6f 6e 73 74 72 61 69 6e 74 20 69 73 20 61 73  constraint is as
35ff0 73 75 6d 65 64 20 74 6f 20 62 65 20 66 75 6c 6c  sumed to be full
36000 79 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68 65  y handled by the
36010 0a 2a 2a 20 76 69 72 74 75 61 6c 20 74 61 62 6c  .** virtual tabl
36020 65 20 61 6e 64 20 69 73 20 6e 6f 74 20 63 68 65  e and is not che
36030 63 6b 65 64 20 61 67 61 69 6e 20 62 79 20 53 51  cked again by SQ
36040 4c 69 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  Lite.)^.**.** ^T
36050 68 65 20 69 64 78 4e 75 6d 20 61 6e 64 20 69 64  he idxNum and id
36060 78 50 74 72 20 76 61 6c 75 65 73 20 61 72 65 20  xPtr values are 
36070 72 65 63 6f 72 64 65 64 20 61 6e 64 20 70 61 73  recorded and pas
36080 73 65 64 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  sed into the.** 
36090 5b 78 46 69 6c 74 65 72 5d 20 6d 65 74 68 6f 64  [xFilter] method
360a0 2e 0a 2a 2a 20 5e 5b 73 71 6c 69 74 65 33 5f 66  ..** ^[sqlite3_f
360b0 72 65 65 28 29 5d 20 69 73 20 75 73 65 64 20 74  ree()] is used t
360c0 6f 20 66 72 65 65 20 69 64 78 50 74 72 20 69 66  o free idxPtr if
360d0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
360e0 6e 65 65 64 54 6f 46 72 65 65 49 64 78 50 74 72  needToFreeIdxPtr
360f0 20 69 73 20 74 72 75 65 2e 0a 2a 2a 0a 2a 2a 20   is true..**.** 
36100 5e 54 68 65 20 6f 72 64 65 72 42 79 43 6f 6e 73  ^The orderByCons
36110 75 6d 65 64 20 6d 65 61 6e 73 20 74 68 61 74 20  umed means that 
36120 6f 75 74 70 75 74 20 66 72 6f 6d 20 5b 78 46 69  output from [xFi
36130 6c 74 65 72 5d 2f 5b 78 4e 65 78 74 5d 20 77 69  lter]/[xNext] wi
36140 6c 6c 20 6f 63 63 75 72 20 69 6e 0a 2a 2a 20 74  ll occur in.** t
36150 68 65 20 63 6f 72 72 65 63 74 20 6f 72 64 65 72  he correct order
36160 20 74 6f 20 73 61 74 69 73 66 79 20 74 68 65 20   to satisfy the 
36170 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
36180 73 6f 20 74 68 61 74 20 6e 6f 20 73 65 70 61 72  so that no separ
36190 61 74 65 0a 2a 2a 20 73 6f 72 74 69 6e 67 20 73  ate.** sorting s
361a0 74 65 70 20 69 73 20 72 65 71 75 69 72 65 64 2e  tep is required.
361b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 65 73 74 69  .**.** ^The esti
361c0 6d 61 74 65 64 43 6f 73 74 20 76 61 6c 75 65 20  matedCost value 
361d0 69 73 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f  is an estimate o
361e0 66 20 74 68 65 20 63 6f 73 74 20 6f 66 20 64 6f  f the cost of do
361f0 69 6e 67 20 74 68 65 0a 2a 2a 20 70 61 72 74 69  ing the.** parti
36200 63 75 6c 61 72 20 6c 6f 6f 6b 75 70 2e 20 20 41  cular lookup.  A
36210 20 66 75 6c 6c 20 73 63 61 6e 20 6f 66 20 61 20   full scan of a 
36220 74 61 62 6c 65 20 77 69 74 68 20 4e 20 65 6e 74  table with N ent
36230 72 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65  ries should have
36240 0a 2a 2a 20 61 20 63 6f 73 74 20 6f 66 20 4e 2e  .** a cost of N.
36250 20 20 41 20 62 69 6e 61 72 79 20 73 65 61 72 63    A binary searc
36260 68 20 6f 66 20 61 20 74 61 62 6c 65 20 6f 66 20  h of a table of 
36270 4e 20 65 6e 74 72 69 65 73 20 73 68 6f 75 6c 64  N entries should
36280 20 68 61 76 65 20 61 0a 2a 2a 20 63 6f 73 74 20   have a.** cost 
36290 6f 66 20 61 70 70 72 6f 78 69 6d 61 74 65 6c 79  of approximately
362a0 20 6c 6f 67 28 4e 29 2e 0a 2a 2f 0a 73 74 72 75   log(N)..*/.stru
362b0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
362c0 5f 69 6e 66 6f 20 7b 0a 20 20 2f 2a 20 49 6e 70  _info {.  /* Inp
362d0 75 74 73 20 2a 2f 0a 20 20 69 6e 74 20 6e 43 6f  uts */.  int nCo
362e0 6e 73 74 72 61 69 6e 74 3b 20 20 20 20 20 20 20  nstraint;       
362f0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
36300 20 65 6e 74 72 69 65 73 20 69 6e 20 61 43 6f 6e   entries in aCon
36310 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 73 74 72  straint */.  str
36320 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  uct sqlite3_inde
36330 78 5f 63 6f 6e 73 74 72 61 69 6e 74 20 7b 0a 20  x_constraint {. 
36340 20 20 20 20 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b      int iColumn;
36350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
36360 20 43 6f 6c 75 6d 6e 20 6f 6e 20 6c 65 66 74 2d   Column on left-
36370 68 61 6e 64 20 73 69 64 65 20 6f 66 20 63 6f 6e  hand side of con
36380 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 20 20 20  straint */.     
36390 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f 70  unsigned char op
363a0 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e  ;         /* Con
363b0 73 74 72 61 69 6e 74 20 6f 70 65 72 61 74 6f 72  straint operator
363c0 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e 65   */.     unsigne
363d0 64 20 63 68 61 72 20 75 73 61 62 6c 65 3b 20 20  d char usable;  
363e0 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 74 68     /* True if th
363f0 69 73 20 63 6f 6e 73 74 72 61 69 6e 74 20 69 73  is constraint is
36400 20 75 73 61 62 6c 65 20 2a 2f 0a 20 20 20 20 20   usable */.     
36410 69 6e 74 20 69 54 65 72 6d 4f 66 66 73 65 74 3b  int iTermOffset;
36420 20 20 20 20 20 20 20 20 20 20 2f 2a 20 55 73 65            /* Use
36430 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 2d 20 78  d internally - x
36440 42 65 73 74 49 6e 64 65 78 20 73 68 6f 75 6c 64  BestIndex should
36450 20 69 67 6e 6f 72 65 20 2a 2f 0a 20 20 7d 20 2a   ignore */.  } *
36460 61 43 6f 6e 73 74 72 61 69 6e 74 3b 20 20 20 20  aConstraint;    
36470 20 20 20 20 20 20 20 20 2f 2a 20 54 61 62 6c 65          /* Table
36480 20 6f 66 20 57 48 45 52 45 20 63 6c 61 75 73 65   of WHERE clause
36490 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 2a 2f 0a   constraints */.
364a0 20 20 69 6e 74 20 6e 4f 72 64 65 72 42 79 3b 20    int nOrderBy; 
364b0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
364c0 4e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20  Number of terms 
364d0 69 6e 20 74 68 65 20 4f 52 44 45 52 20 42 59 20  in the ORDER BY 
364e0 63 6c 61 75 73 65 20 2a 2f 0a 20 20 73 74 72 75  clause */.  stru
364f0 63 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  ct sqlite3_index
36500 5f 6f 72 64 65 72 62 79 20 7b 0a 20 20 20 20 20  _orderby {.     
36510 69 6e 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20  int iColumn;    
36520 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c            /* Col
36530 75 6d 6e 20 6e 75 6d 62 65 72 20 2a 2f 0a 20 20  umn number */.  
36540 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
36550 20 64 65 73 63 3b 20 20 20 20 20 20 20 2f 2a 20   desc;       /* 
36560 54 72 75 65 20 66 6f 72 20 44 45 53 43 2e 20 20  True for DESC.  
36570 46 61 6c 73 65 20 66 6f 72 20 41 53 43 2e 20 2a  False for ASC. *
36580 2f 0a 20 20 7d 20 2a 61 4f 72 64 65 72 42 79 3b  /.  } *aOrderBy;
36590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
365a0 2a 20 54 68 65 20 4f 52 44 45 52 20 42 59 20 63  * The ORDER BY c
365b0 6c 61 75 73 65 20 2a 2f 0a 20 20 2f 2a 20 4f 75  lause */.  /* Ou
365c0 74 70 75 74 73 20 2a 2f 0a 20 20 73 74 72 75 63  tputs */.  struc
365d0 74 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  t sqlite3_index_
365e0 63 6f 6e 73 74 72 61 69 6e 74 5f 75 73 61 67 65  constraint_usage
365f0 20 7b 0a 20 20 20 20 69 6e 74 20 61 72 67 76 49   {.    int argvI
36600 6e 64 65 78 3b 20 20 20 20 20 20 20 20 20 20 20  ndex;           
36610 2f 2a 20 69 66 20 3e 30 2c 20 63 6f 6e 73 74 72  /* if >0, constr
36620 61 69 6e 74 20 69 73 20 70 61 72 74 20 6f 66 20  aint is part of 
36630 61 72 67 76 20 74 6f 20 78 46 69 6c 74 65 72 20  argv to xFilter 
36640 2a 2f 0a 20 20 20 20 75 6e 73 69 67 6e 65 64 20  */.    unsigned 
36650 63 68 61 72 20 6f 6d 69 74 3b 20 20 20 20 20 20  char omit;      
36660 2f 2a 20 44 6f 20 6e 6f 74 20 63 6f 64 65 20 61  /* Do not code a
36670 20 74 65 73 74 20 66 6f 72 20 74 68 69 73 20 63   test for this c
36680 6f 6e 73 74 72 61 69 6e 74 20 2a 2f 0a 20 20 7d  onstraint */.  }
36690 20 2a 61 43 6f 6e 73 74 72 61 69 6e 74 55 73 61   *aConstraintUsa
366a0 67 65 3b 0a 20 20 69 6e 74 20 69 64 78 4e 75 6d  ge;.  int idxNum
366b0 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
366c0 20 2f 2a 20 4e 75 6d 62 65 72 20 75 73 65 64 20   /* Number used 
366d0 74 6f 20 69 64 65 6e 74 69 66 79 20 74 68 65 20  to identify the 
366e0 69 6e 64 65 78 20 2a 2f 0a 20 20 63 68 61 72 20  index */.  char 
366f0 2a 69 64 78 53 74 72 3b 20 20 20 20 20 20 20 20  *idxStr;        
36700 20 20 20 20 20 20 2f 2a 20 53 74 72 69 6e 67 2c        /* String,
36710 20 70 6f 73 73 69 62 6c 79 20 6f 62 74 61 69 6e   possibly obtain
36720 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
36730 6d 61 6c 6c 6f 63 20 2a 2f 0a 20 20 69 6e 74 20  malloc */.  int 
36740 6e 65 65 64 54 6f 46 72 65 65 49 64 78 53 74 72  needToFreeIdxStr
36750 3b 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 69  ;      /* Free i
36760 64 78 53 74 72 20 75 73 69 6e 67 20 73 71 6c 69  dxStr using sqli
36770 74 65 33 5f 66 72 65 65 28 29 20 69 66 20 74 72  te3_free() if tr
36780 75 65 20 2a 2f 0a 20 20 69 6e 74 20 6f 72 64 65  ue */.  int orde
36790 72 42 79 43 6f 6e 73 75 6d 65 64 3b 20 20 20 20  rByConsumed;    
367a0 20 20 20 2f 2a 20 54 72 75 65 20 69 66 20 6f 75     /* True if ou
367b0 74 70 75 74 20 69 73 20 61 6c 72 65 61 64 79 20  tput is already 
367c0 6f 72 64 65 72 65 64 20 2a 2f 0a 20 20 64 6f 75  ordered */.  dou
367d0 62 6c 65 20 65 73 74 69 6d 61 74 65 64 43 6f 73  ble estimatedCos
367e0 74 3b 20 20 20 20 20 20 2f 2a 20 45 73 74 69 6d  t;      /* Estim
367f0 61 74 65 64 20 63 6f 73 74 20 6f 66 20 75 73 69  ated cost of usi
36800 6e 67 20 74 68 69 73 20 69 6e 64 65 78 20 2a 2f  ng this index */
36810 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
36820 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61 62  REF: Virtual Tab
36830 6c 65 20 43 6f 6e 73 74 72 61 69 6e 74 20 4f 70  le Constraint Op
36840 65 72 61 74 6f 72 20 43 6f 64 65 73 0a 2a 2a 0a  erator Codes.**.
36850 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20  ** These macros 
36860 64 65 66 69 6e 65 64 20 74 68 65 20 61 6c 6c 6f  defined the allo
36870 77 65 64 20 76 61 6c 75 65 73 20 66 6f 72 20 74  wed values for t
36880 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  he.** [sqlite3_i
36890 6e 64 65 78 5f 69 6e 66 6f 5d 2e 61 43 6f 6e 73  ndex_info].aCons
368a0 74 72 61 69 6e 74 5b 5d 2e 6f 70 20 66 69 65 6c  traint[].op fiel
368b0 64 2e 20 20 45 61 63 68 20 76 61 6c 75 65 20 72  d.  Each value r
368c0 65 70 72 65 73 65 6e 74 73 0a 2a 2a 20 61 6e 20  epresents.** an 
368d0 6f 70 65 72 61 74 6f 72 20 74 68 61 74 20 69 73  operator that is
368e0 20 70 61 72 74 20 6f 66 20 61 20 63 6f 6e 73 74   part of a const
368f0 72 61 69 6e 74 20 74 65 72 6d 20 69 6e 20 74 68  raint term in th
36900 65 20 77 48 45 52 45 20 63 6c 61 75 73 65 20 6f  e wHERE clause o
36910 66 0a 2a 2a 20 61 20 71 75 65 72 79 20 74 68 61  f.** a query tha
36920 74 20 75 73 65 73 20 61 20 5b 76 69 72 74 75 61  t uses a [virtua
36930 6c 20 74 61 62 6c 65 5d 2e 0a 2a 2f 0a 23 64 65  l table]..*/.#de
36940 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
36950 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 45 51 20  X_CONSTRAINT_EQ 
36960 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
36970 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
36980 41 49 4e 54 5f 47 54 20 20 20 20 34 0a 23 64 65  AINT_GT    4.#de
36990 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44 45  fine SQLITE_INDE
369a0 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c 45 20  X_CONSTRAINT_LE 
369b0 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
369c0 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52  ITE_INDEX_CONSTR
369d0 41 49 4e 54 5f 4c 54 20 20 20 20 31 36 0a 23 64  AINT_LT    16.#d
369e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 44  efine SQLITE_IND
369f0 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47 45  EX_CONSTRAINT_GE
36a00 20 20 20 20 33 32 0a 23 64 65 66 69 6e 65 20 53      32.#define S
36a10 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
36a20 54 52 41 49 4e 54 5f 4d 41 54 43 48 20 36 34 0a  TRAINT_MATCH 64.
36a30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36a40 20 52 65 67 69 73 74 65 72 20 41 20 56 69 72 74   Register A Virt
36a50 75 61 6c 20 54 61 62 6c 65 20 49 6d 70 6c 65 6d  ual Table Implem
36a60 65 6e 74 61 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  entation.**.** ^
36a70 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
36a80 72 65 20 75 73 65 64 20 74 6f 20 72 65 67 69 73  re used to regis
36a90 74 65 72 20 61 20 6e 65 77 20 5b 76 69 72 74 75  ter a new [virtu
36aa0 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
36ab0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 4d 6f 64 75 6c   name..** ^Modul
36ac0 65 20 6e 61 6d 65 73 20 6d 75 73 74 20 62 65 20  e names must be 
36ad0 72 65 67 69 73 74 65 72 65 64 20 62 65 66 6f 72  registered befor
36ae0 65 0a 2a 2a 20 63 72 65 61 74 69 6e 67 20 61 20  e.** creating a 
36af0 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62  new [virtual tab
36b00 6c 65 5d 20 75 73 69 6e 67 20 74 68 65 20 6d 6f  le] using the mo
36b10 64 75 6c 65 20 61 6e 64 20 62 65 66 6f 72 65 20  dule and before 
36b20 75 73 69 6e 67 20 61 0a 2a 2a 20 70 72 65 65 78  using a.** preex
36b30 69 73 74 69 6e 67 20 5b 76 69 72 74 75 61 6c 20  isting [virtual 
36b40 74 61 62 6c 65 5d 20 66 6f 72 20 74 68 65 20 6d  table] for the m
36b50 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  odule..**.** ^Th
36b60 65 20 6d 6f 64 75 6c 65 20 6e 61 6d 65 20 69 73  e module name is
36b70 20 72 65 67 69 73 74 65 72 65 64 20 6f 6e 20 74   registered on t
36b80 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36b90 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
36ba0 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 66 69 72  ed.** by the fir
36bb0 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  st parameter.  ^
36bc0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
36bd0 6d 6f 64 75 6c 65 20 69 73 20 67 69 76 65 6e 20  module is given 
36be0 62 79 20 74 68 65 20 0a 2a 2a 20 73 65 63 6f 6e  by the .** secon
36bf0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54  d parameter.  ^T
36c00 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
36c10 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
36c20 74 6f 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  to.** the implem
36c30 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
36c40 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d  [virtual table m
36c50 6f 64 75 6c 65 5d 2e 20 20 20 5e 54 68 65 20 66  odule].   ^The f
36c60 6f 75 72 74 68 0a 2a 2a 20 70 61 72 61 6d 65 74  ourth.** paramet
36c70 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61  er is an arbitra
36c80 72 79 20 63 6c 69 65 6e 74 20 64 61 74 61 20 70  ry client data p
36c90 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
36ca0 61 73 73 65 64 20 74 68 72 6f 75 67 68 0a 2a 2a  assed through.**
36cb0 20 69 6e 74 6f 20 74 68 65 20 5b 78 43 72 65 61   into the [xCrea
36cc0 74 65 5d 20 61 6e 64 20 5b 78 43 6f 6e 6e 65 63  te] and [xConnec
36cd0 74 5d 20 6d 65 74 68 6f 64 73 20 6f 66 20 74 68  t] methods of th
36ce0 65 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  e virtual table 
36cf0 6d 6f 64 75 6c 65 0a 2a 2a 20 77 68 65 6e 20 61  module.** when a
36d00 20 6e 65 77 20 76 69 72 74 75 61 6c 20 74 61 62   new virtual tab
36d10 6c 65 20 69 73 20 62 65 20 62 65 69 6e 67 20 63  le is be being c
36d20 72 65 61 74 65 64 20 6f 72 20 72 65 69 6e 69 74  reated or reinit
36d30 69 61 6c 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ialized..**.** ^
36d40 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  The sqlite3_crea
36d50 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 29 20 69  te_module_v2() i
36d60 6e 74 65 72 66 61 63 65 20 68 61 73 20 61 20 66  nterface has a f
36d70 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 77  ifth parameter w
36d80 68 69 63 68 0a 2a 2a 20 69 73 20 61 20 70 6f 69  hich.** is a poi
36d90 6e 74 65 72 20 74 6f 20 61 20 64 65 73 74 72 75  nter to a destru
36da0 63 74 6f 72 20 66 6f 72 20 74 68 65 20 70 43 6c  ctor for the pCl
36db0 69 65 6e 74 44 61 74 61 2e 20 20 5e 53 51 4c 69  ientData.  ^SQLi
36dc0 74 65 20 77 69 6c 6c 0a 2a 2a 20 69 6e 76 6f 6b  te will.** invok
36dd0 65 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  e the destructor
36de0 20 66 75 6e 63 74 69 6f 6e 20 28 69 66 20 69 74   function (if it
36df0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 77 68   is not NULL) wh
36e00 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 6e 6f 20  en SQLite.** no 
36e10 6c 6f 6e 67 65 72 20 6e 65 65 64 73 20 74 68 65  longer needs the
36e20 20 70 43 6c 69 65 6e 74 44 61 74 61 20 70 6f 69   pClientData poi
36e30 6e 74 65 72 2e 20 20 5e 54 68 65 20 64 65 73 74  nter.  ^The dest
36e40 72 75 63 74 6f 72 20 77 69 6c 6c 20 61 6c 73 6f  ructor will also
36e50 0a 2a 2a 20 62 65 20 69 6e 76 6f 6b 65 64 20 69  .** be invoked i
36e60 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71  f the call to sq
36e70 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
36e80 75 6c 65 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ule_v2() fails..
36e90 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36ea0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28 29 0a  create_module().
36eb0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
36ec0 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 71  equivalent to sq
36ed0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
36ee0 75 6c 65 5f 76 32 28 29 20 77 69 74 68 20 61 20  ule_v2() with a 
36ef0 4e 55 4c 4c 0a 2a 2a 20 64 65 73 74 72 75 63 74  NULL.** destruct
36f00 6f 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  or..*/.SQLITE_AP
36f10 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
36f20 65 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73  eate_module(.  s
36f30 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
36f40 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c            /* SQL
36f50 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ite connection t
36f60 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c  o register modul
36f70 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73  e with */.  cons
36f80 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20  t char *zName,  
36f90 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
36fa0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a  f the module */.
36fb0 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f    const sqlite3_
36fc0 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20  module *p,   /* 
36fd0 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20  Methods for the 
36fe0 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64  module */.  void
36ff0 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20   *pClientData   
37000 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74         /* Client
37010 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74   data for xCreat
37020 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b  e/xConnect */.);
37030 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
37040 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d  sqlite3_create_m
37050 6f 64 75 6c 65 5f 76 32 28 0a 20 20 73 71 6c 69  odule_v2(.  sqli
37060 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
37070 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69 74 65         /* SQLite
37080 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72   connection to r
37090 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65 20 77  egister module w
370a0 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ith */.  const c
370b0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20 20 20  har *zName,     
370c0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
370d0 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 63  he module */.  c
370e0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  onst sqlite3_mod
370f0 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d 65 74  ule *p,   /* Met
37100 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d 6f 64  hods for the mod
37110 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  ule */.  void *p
37120 43 6c 69 65 6e 74 44 61 74 61 2c 20 20 20 20 20  ClientData,     
37130 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20 64 61      /* Client da
37140 74 61 20 66 6f 72 20 78 43 72 65 61 74 65 2f 78  ta for xCreate/x
37150 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20 20 76 6f 69  Connect */.  voi
37160 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
37170 64 2a 29 20 20 20 20 20 2f 2a 20 4d 6f 64 75 6c  d*)     /* Modul
37180 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e  e destructor fun
37190 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  ction */.);../*.
371a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
371b0 74 75 61 6c 20 54 61 62 6c 65 20 49 6e 73 74 61  tual Table Insta
371c0 6e 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  nce Object.** KE
371d0 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
371e0 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  vtab.**.** Every
371f0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
37200 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c 65 6d 65 6e  module] implemen
37210 74 61 74 69 6f 6e 20 75 73 65 73 20 61 20 73 75  tation uses a su
37220 62 63 6c 61 73 73 0a 2a 2a 20 6f 66 20 74 68 69  bclass.** of thi
37230 73 20 6f 62 6a 65 63 74 20 74 6f 20 64 65 73 63  s object to desc
37240 72 69 62 65 20 61 20 70 61 72 74 69 63 75 6c 61  ribe a particula
37250 72 20 69 6e 73 74 61 6e 63 65 0a 2a 2a 20 6f 66  r instance.** of
37260 20 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61   the [virtual ta
37270 62 6c 65 5d 2e 20 20 45 61 63 68 20 73 75 62 63  ble].  Each subc
37280 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a 20 62 65 20  lass will.** be 
37290 74 61 69 6c 6f 72 65 64 20 74 6f 20 74 68 65 20  tailored to the 
372a0 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
372b0 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 69 6d 70  f the module imp
372c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 0a 2a 2a 20  lementation..** 
372d0 54 68 65 20 70 75 72 70 6f 73 65 20 6f 66 20 74  The purpose of t
372e0 68 69 73 20 73 75 70 65 72 63 6c 61 73 73 20 69  his superclass i
372f0 73 20 74 6f 20 64 65 66 69 6e 65 20 63 65 72 74  s to define cert
37300 61 69 6e 20 66 69 65 6c 64 73 20 74 68 61 74 20  ain fields that 
37310 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f 6e 20 74 6f  are.** common to
37320 20 61 6c 6c 20 6d 6f 64 75 6c 65 20 69 6d 70 6c   all module impl
37330 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0a 2a 2a 0a  ementations..**.
37340 2a 2a 20 5e 56 69 72 74 75 61 6c 20 74 61 62 6c  ** ^Virtual tabl
37350 65 73 20 6d 65 74 68 6f 64 73 20 63 61 6e 20 73  es methods can s
37360 65 74 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  et an error mess
37370 61 67 65 20 62 79 20 61 73 73 69 67 6e 69 6e 67  age by assigning
37380 20 61 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 62 74   a.** string obt
37390 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
373a0 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 20 74  te3_mprintf()] t
373b0 6f 20 7a 45 72 72 4d 73 67 2e 20 20 54 68 65 20  o zErrMsg.  The 
373c0 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 0a 2a 2a  method should.**
373d0 20 74 61 6b 65 20 63 61 72 65 20 74 68 61 74 20   take care that 
373e0 61 6e 79 20 70 72 69 6f 72 20 73 74 72 69 6e 67  any prior string
373f0 20 69 73 20 66 72 65 65 64 20 62 79 20 61 20 63   is freed by a c
37400 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
37410 66 72 65 65 28 29 5d 0a 2a 2a 20 70 72 69 6f 72  free()].** prior
37420 20 74 6f 20 61 73 73 69 67 6e 69 6e 67 20 61 20   to assigning a 
37430 6e 65 77 20 73 74 72 69 6e 67 20 74 6f 20 7a 45  new string to zE
37440 72 72 4d 73 67 2e 20 20 5e 41 66 74 65 72 20 74  rrMsg.  ^After t
37450 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
37460 0a 2a 2a 20 69 73 20 64 65 6c 69 76 65 72 65 64  .** is delivered
37470 20 75 70 20 74 6f 20 74 68 65 20 63 6c 69 65 6e   up to the clien
37480 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  t application, t
37490 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
374a0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  e automatically.
374b0 2a 2a 20 66 72 65 65 64 20 62 79 20 73 71 6c 69  ** freed by sqli
374c0 74 65 33 5f 66 72 65 65 28 29 20 61 6e 64 20 74  te3_free() and t
374d0 68 65 20 7a 45 72 72 4d 73 67 20 66 69 65 6c 64  he zErrMsg field
374e0 20 77 69 6c 6c 20 62 65 20 7a 65 72 6f 65 64 2e   will be zeroed.
374f0 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69 74  .*/.struct sqlit
37500 65 33 5f 76 74 61 62 20 7b 0a 20 20 63 6f 6e 73  e3_vtab {.  cons
37510 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65  t sqlite3_module
37520 20 2a 70 4d 6f 64 75 6c 65 3b 20 20 2f 2a 20 54   *pModule;  /* T
37530 68 65 20 6d 6f 64 75 6c 65 20 66 6f 72 20 74 68  he module for th
37540 69 73 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  is virtual table
37550 20 2a 2f 0a 20 20 69 6e 74 20 6e 52 65 66 3b 20   */.  int nRef; 
37560 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37570 20 20 20 20 20 20 2f 2a 20 4e 4f 20 4c 4f 4e 47        /* NO LONG
37580 45 52 20 55 53 45 44 20 2a 2f 0a 20 20 63 68 61  ER USED */.  cha
37590 72 20 2a 7a 45 72 72 4d 73 67 3b 20 20 20 20 20  r *zErrMsg;     
375a0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
375b0 45 72 72 6f 72 20 6d 65 73 73 61 67 65 20 66 72  Error message fr
375c0 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  om sqlite3_mprin
375d0 74 66 28 29 20 2a 2f 0a 20 20 2f 2a 20 56 69 72  tf() */.  /* Vir
375e0 74 75 61 6c 20 74 61 62 6c 65 20 69 6d 70 6c 65  tual table imple
375f0 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 20  mentations will 
37600 74 79 70 69 63 61 6c 6c 79 20 61 64 64 20 61 64  typically add ad
37610 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20  ditional fields 
37620 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
37630 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
37640 61 62 6c 65 20 43 75 72 73 6f 72 20 4f 62 6a 65  able Cursor Obje
37650 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
37660 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72  sqlite3_vtab_cur
37670 73 6f 72 20 7b 76 69 72 74 75 61 6c 20 74 61 62  sor {virtual tab
37680 6c 65 20 63 75 72 73 6f 72 7d 0a 2a 2a 0a 2a 2a  le cursor}.**.**
37690 20 45 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20   Every [virtual 
376a0 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d  table module] im
376b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65  plementation use
376c0 73 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20  s a subclass of 
376d0 74 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  the.** following
376e0 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 64 65   structure to de
376f0 73 63 72 69 62 65 20 63 75 72 73 6f 72 73 20 74  scribe cursors t
37700 68 61 74 20 70 6f 69 6e 74 20 69 6e 74 6f 20 74  hat point into t
37710 68 65 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74  he.** [virtual t
37720 61 62 6c 65 5d 20 61 6e 64 20 61 72 65 20 75 73  able] and are us
37730 65 64 0a 2a 2a 20 74 6f 20 6c 6f 6f 70 20 74 68  ed.** to loop th
37740 72 6f 75 67 68 20 74 68 65 20 76 69 72 74 75 61  rough the virtua
37750 6c 20 74 61 62 6c 65 2e 20 20 43 75 72 73 6f 72  l table.  Cursor
37760 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73  s are created us
37770 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
37780 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 4f 70 65 6e  te3_module.xOpen
37790 20 7c 20 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64   | xOpen] method
377a0 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 61   of the module a
377b0 6e 64 20 61 72 65 20 64 65 73 74 72 6f 79 65 64  nd are destroyed
377c0 0a 2a 2a 20 62 79 20 74 68 65 20 5b 73 71 6c 69  .** by the [sqli
377d0 74 65 33 5f 6d 6f 64 75 6c 65 2e 78 43 6c 6f 73  te3_module.xClos
377e0 65 20 7c 20 78 43 6c 6f 73 65 5d 20 6d 65 74 68  e | xClose] meth
377f0 6f 64 2e 20 20 43 75 72 73 6f 72 73 20 61 72 65  od.  Cursors are
37800 20 75 73 65 64 0a 2a 2a 20 62 79 20 74 68 65 20   used.** by the 
37810 5b 78 46 69 6c 74 65 72 5d 2c 20 5b 78 4e 65 78  [xFilter], [xNex
37820 74 5d 2c 20 5b 78 45 6f 66 5d 2c 20 5b 78 43 6f  t], [xEof], [xCo
37830 6c 75 6d 6e 5d 2c 20 61 6e 64 20 5b 78 52 6f 77  lumn], and [xRow
37840 69 64 5d 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f  id] methods.** o
37850 66 20 74 68 65 20 6d 6f 64 75 6c 65 2e 20 20 45  f the module.  E
37860 61 63 68 20 6d 6f 64 75 6c 65 20 69 6d 70 6c 65  ach module imple
37870 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 64  mentation will d
37880 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 63 6f 6e  efine.** the con
37890 74 65 6e 74 20 6f 66 20 61 20 63 75 72 73 6f 72  tent of a cursor
378a0 20 73 74 72 75 63 74 75 72 65 20 74 6f 20 73 75   structure to su
378b0 69 74 20 69 74 73 20 6f 77 6e 20 6e 65 65 64 73  it its own needs
378c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 75 70  ..**.** This sup
378d0 65 72 63 6c 61 73 73 20 65 78 69 73 74 73 20 69  erclass exists i
378e0 6e 20 6f 72 64 65 72 20 74 6f 20 64 65 66 69 6e  n order to defin
378f0 65 20 66 69 65 6c 64 73 20 6f 66 20 74 68 65 20  e fields of the 
37900 63 75 72 73 6f 72 20 74 68 61 74 0a 2a 2a 20 61  cursor that.** a
37910 72 65 20 63 6f 6d 6d 6f 6e 20 74 6f 20 61 6c 6c  re common to all
37920 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
37930 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c 69  ..*/.struct sqli
37940 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20  te3_vtab_cursor 
37950 7b 0a 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62  {.  sqlite3_vtab
37960 20 2a 70 56 74 61 62 3b 20 20 20 20 20 20 2f 2a   *pVtab;      /*
37970 20 56 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6f   Virtual table o
37980 66 20 74 68 69 73 20 63 75 72 73 6f 72 20 2a 2f  f this cursor */
37990 0a 20 20 2f 2a 20 56 69 72 74 75 61 6c 20 74 61  .  /* Virtual ta
379a0 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
379b0 6f 6e 73 20 77 69 6c 6c 20 74 79 70 69 63 61 6c  ons will typical
379c0 6c 79 20 61 64 64 20 61 64 64 69 74 69 6f 6e 61  ly add additiona
379d0 6c 20 66 69 65 6c 64 73 20 2a 2f 0a 7d 3b 0a 0a  l fields */.};..
379e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
379f0 44 65 63 6c 61 72 65 20 54 68 65 20 53 63 68 65  Declare The Sche
37a00 6d 61 20 4f 66 20 41 20 56 69 72 74 75 61 6c 20  ma Of A Virtual 
37a10 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Table.**.** ^The
37a20 20 5b 78 43 72 65 61 74 65 5d 20 61 6e 64 20 5b   [xCreate] and [
37a30 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74 68 6f 64  xConnect] method
37a40 73 20 6f 66 20 61 0a 2a 2a 20 5b 76 69 72 74 75  s of a.** [virtu
37a50 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
37a60 20 63 61 6c 6c 20 74 68 69 73 20 69 6e 74 65 72   call this inter
37a70 66 61 63 65 0a 2a 2a 20 74 6f 20 64 65 63 6c 61  face.** to decla
37a80 72 65 20 74 68 65 20 66 6f 72 6d 61 74 20 28 74  re the format (t
37a90 68 65 20 6e 61 6d 65 73 20 61 6e 64 20 64 61 74  he names and dat
37aa0 61 74 79 70 65 73 20 6f 66 20 74 68 65 20 63 6f  atypes of the co
37ab0 6c 75 6d 6e 73 29 20 6f 66 0a 2a 2a 20 74 68 65  lumns) of.** the
37ac0 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 20   virtual tables 
37ad0 74 68 65 79 20 69 6d 70 6c 65 6d 65 6e 74 2e 0a  they implement..
37ae0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
37af0 74 20 73 71 6c 69 74 65 33 5f 64 65 63 6c 61 72  t sqlite3_declar
37b00 65 5f 76 74 61 62 28 73 71 6c 69 74 65 33 2a 2c  e_vtab(sqlite3*,
37b10 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 51   const char *zSQ
37b20 4c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  L);../*.** CAPI3
37b30 52 45 46 3a 20 4f 76 65 72 6c 6f 61 64 20 41 20  REF: Overload A 
37b40 46 75 6e 63 74 69 6f 6e 20 46 6f 72 20 41 20 56  Function For A V
37b50 69 72 74 75 61 6c 20 54 61 62 6c 65 0a 2a 2a 0a  irtual Table.**.
37b60 2a 2a 20 5e 28 56 69 72 74 75 61 6c 20 74 61 62  ** ^(Virtual tab
37b70 6c 65 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20  les can provide 
37b80 61 6c 74 65 72 6e 61 74 69 76 65 20 69 6d 70 6c  alternative impl
37b90 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 66  ementations of f
37ba0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 75 73 69 6e  unctions.** usin
37bb0 67 20 74 68 65 20 5b 78 46 69 6e 64 46 75 6e 63  g the [xFindFunc
37bc0 74 69 6f 6e 5d 20 6d 65 74 68 6f 64 20 6f 66 20  tion] method of 
37bd0 74 68 65 20 5b 76 69 72 74 75 61 6c 20 74 61 62  the [virtual tab
37be0 6c 65 20 6d 6f 64 75 6c 65 5d 2e 20 20 0a 2a 2a  le module].  .**
37bf0 20 42 75 74 20 67 6c 6f 62 61 6c 20 76 65 72 73   But global vers
37c00 69 6f 6e 73 20 6f 66 20 74 68 6f 73 65 20 66 75  ions of those fu
37c10 6e 63 74 69 6f 6e 73 0a 2a 2a 20 6d 75 73 74 20  nctions.** must 
37c20 65 78 69 73 74 20 69 6e 20 6f 72 64 65 72 20 74  exist in order t
37c30 6f 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 2e  o be overloaded.
37c40 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  )^.**.** ^(This 
37c50 41 50 49 20 6d 61 6b 65 73 20 73 75 72 65 20 61  API makes sure a
37c60 20 67 6c 6f 62 61 6c 20 76 65 72 73 69 6f 6e 20   global version 
37c70 6f 66 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  of a function wi
37c80 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
37c90 2a 2a 20 6e 61 6d 65 20 61 6e 64 20 6e 75 6d 62  ** name and numb
37ca0 65 72 20 6f 66 20 70 61 72 61 6d 65 74 65 72 73  er of parameters
37cb0 20 65 78 69 73 74 73 2e 20 20 49 66 20 6e 6f 20   exists.  If no 
37cc0 73 75 63 68 20 66 75 6e 63 74 69 6f 6e 20 65 78  such function ex
37cd0 69 73 74 73 0a 2a 2a 20 62 65 66 6f 72 65 20 74  ists.** before t
37ce0 68 69 73 20 41 50 49 20 69 73 20 63 61 6c 6c 65  his API is calle
37cf0 64 2c 20 61 20 6e 65 77 20 66 75 6e 63 74 69 6f  d, a new functio
37d00 6e 20 69 73 20 63 72 65 61 74 65 64 2e 29 5e 20  n is created.)^ 
37d10 20 5e 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61   ^The implementa
37d20 74 69 6f 6e 0a 2a 2a 20 6f 66 20 74 68 65 20 6e  tion.** of the n
37d30 65 77 20 66 75 6e 63 74 69 6f 6e 20 61 6c 77 61  ew function alwa
37d40 79 73 20 63 61 75 73 65 73 20 61 6e 20 65 78 63  ys causes an exc
37d50 65 70 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 72  eption to be thr
37d60 6f 77 6e 2e 20 20 53 6f 0a 2a 2a 20 74 68 65 20  own.  So.** the 
37d70 6e 65 77 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  new function is 
37d80 6e 6f 74 20 67 6f 6f 64 20 66 6f 72 20 61 6e 79  not good for any
37d90 74 68 69 6e 67 20 62 79 20 69 74 73 65 6c 66 2e  thing by itself.
37da0 20 20 49 74 73 20 6f 6e 6c 79 0a 2a 2a 20 70 75    Its only.** pu
37db0 72 70 6f 73 65 20 69 73 20 74 6f 20 62 65 20 61  rpose is to be a
37dc0 20 70 6c 61 63 65 68 6f 6c 64 65 72 20 66 75 6e   placeholder fun
37dd0 63 74 69 6f 6e 20 74 68 61 74 20 63 61 6e 20 62  ction that can b
37de0 65 20 6f 76 65 72 6c 6f 61 64 65 64 0a 2a 2a 20  e overloaded.** 
37df0 62 79 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61  by a [virtual ta
37e00 62 6c 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ble]..*/.SQLITE_
37e10 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
37e20 6f 76 65 72 6c 6f 61 64 5f 66 75 6e 63 74 69 6f  overload_functio
37e30 6e 28 73 71 6c 69 74 65 33 2a 2c 20 63 6f 6e 73  n(sqlite3*, cons
37e40 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 4e 61 6d  t char *zFuncNam
37e50 65 2c 20 69 6e 74 20 6e 41 72 67 29 3b 0a 0a 2f  e, int nArg);../
37e60 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66 61  *.** The interfa
37e70 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75 61  ce to the virtua
37e80 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69 73  l-table mechanis
37e90 6d 20 64 65 66 69 6e 65 64 20 61 62 6f 76 65 20  m defined above 
37ea0 28 62 61 63 6b 20 75 70 0a 2a 2a 20 74 6f 20 61  (back up.** to a
37eb0 20 63 6f 6d 6d 65 6e 74 20 72 65 6d 61 72 6b 61   comment remarka
37ec0 62 6c 79 20 73 69 6d 69 6c 61 72 20 74 6f 20 74  bly similar to t
37ed0 68 69 73 20 6f 6e 65 29 20 69 73 20 63 75 72 72  his one) is curr
37ee0 65 6e 74 6c 79 20 63 6f 6e 73 69 64 65 72 65 64  ently considered
37ef0 0a 2a 2a 20 74 6f 20 62 65 20 65 78 70 65 72 69  .** to be experi
37f00 6d 65 6e 74 61 6c 2e 20 20 54 68 65 20 69 6e 74  mental.  The int
37f10 65 72 66 61 63 65 20 6d 69 67 68 74 20 63 68 61  erface might cha
37f20 6e 67 65 20 69 6e 20 69 6e 63 6f 6d 70 61 74 69  nge in incompati
37f30 62 6c 65 20 77 61 79 73 2e 0a 2a 2a 20 49 66 20  ble ways..** If 
37f40 74 68 69 73 20 69 73 20 61 20 70 72 6f 62 6c 65  this is a proble
37f50 6d 20 66 6f 72 20 79 6f 75 2c 20 64 6f 20 6e 6f  m for you, do no
37f60 74 20 75 73 65 20 74 68 65 20 69 6e 74 65 72 66  t use the interf
37f70 61 63 65 20 61 74 20 74 68 69 73 20 74 69 6d 65  ace at this time
37f80 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
37f90 20 76 69 72 74 75 61 6c 2d 74 61 62 6c 65 20 6d   virtual-table m
37fa0 65 63 68 61 6e 69 73 6d 20 73 74 61 62 69 6c 69  echanism stabili
37fb0 7a 65 73 2c 20 77 65 20 77 69 6c 6c 20 64 65 63  zes, we will dec
37fc0 6c 61 72 65 20 74 68 65 0a 2a 2a 20 69 6e 74 65  lare the.** inte
37fd0 72 66 61 63 65 20 66 69 78 65 64 2c 20 73 75 70  rface fixed, sup
37fe0 70 6f 72 74 20 69 74 20 69 6e 64 65 66 69 6e 69  port it indefini
37ff0 74 65 6c 79 2c 20 61 6e 64 20 72 65 6d 6f 76 65  tely, and remove
38000 20 74 68 69 73 20 63 6f 6d 6d 65 6e 74 2e 0a 2a   this comment..*
38010 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
38020 46 3a 20 41 20 48 61 6e 64 6c 65 20 54 6f 20 41  F: A Handle To A
38030 6e 20 4f 70 65 6e 20 42 4c 4f 42 0a 2a 2a 20 4b  n Open BLOB.** K
38040 45 59 57 4f 52 44 53 3a 20 7b 42 4c 4f 42 20 68  EYWORDS: {BLOB h
38050 61 6e 64 6c 65 7d 20 7b 42 4c 4f 42 20 68 61 6e  andle} {BLOB han
38060 64 6c 65 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69  dles}.**.** An i
38070 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
38080 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
38090 73 20 61 6e 20 6f 70 65 6e 20 42 4c 4f 42 20 6f  s an open BLOB o
380a0 6e 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  n which.** [sqli
380b0 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20  te3_blob_open | 
380c0 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42  incremental BLOB
380d0 20 49 2f 4f 5d 20 63 61 6e 20 62 65 20 70 65 72   I/O] can be per
380e0 66 6f 72 6d 65 64 2e 0a 2a 2a 20 5e 4f 62 6a 65  formed..** ^Obje
380f0 63 74 73 20 6f 66 20 74 68 69 73 20 74 79 70 65  cts of this type
38100 20 61 72 65 20 63 72 65 61 74 65 64 20 62 79 20   are created by 
38110 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
38120 65 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 64 65 73  en()].** and des
38130 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74  troyed by [sqlit
38140 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d  e3_blob_close()]
38150 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  ..** ^The [sqlit
38160 65 33 5f 62 6c 6f 62 5f 72 65 61 64 28 29 5d 20  e3_blob_read()] 
38170 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  and [sqlite3_blo
38180 62 5f 77 72 69 74 65 28 29 5d 20 69 6e 74 65 72  b_write()] inter
38190 66 61 63 65 73 0a 2a 2a 20 63 61 6e 20 62 65 20  faces.** can be 
381a0 75 73 65 64 20 74 6f 20 72 65 61 64 20 6f 72 20  used to read or 
381b0 77 72 69 74 65 20 73 6d 61 6c 6c 20 73 75 62 73  write small subs
381c0 65 63 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 42  ections of the B
381d0 4c 4f 42 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  LOB..** ^The [sq
381e0 6c 69 74 65 33 5f 62 6c 6f 62 5f 62 79 74 65 73  lite3_blob_bytes
381f0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  ()] interface re
38200 74 75 72 6e 73 20 74 68 65 20 73 69 7a 65 20 6f  turns the size o
38210 66 20 74 68 65 20 42 4c 4f 42 20 69 6e 20 62 79  f the BLOB in by
38220 74 65 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  tes..*/.typedef 
38230 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 62  struct sqlite3_b
38240 6c 6f 62 20 73 71 6c 69 74 65 33 5f 62 6c 6f 62  lob sqlite3_blob
38250 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
38260 46 3a 20 4f 70 65 6e 20 41 20 42 4c 4f 42 20 46  F: Open A BLOB F
38270 6f 72 20 49 6e 63 72 65 6d 65 6e 74 61 6c 20 49  or Incremental I
38280 2f 4f 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  /O.**.** ^(This 
38290 69 6e 74 65 72 66 61 63 65 73 20 6f 70 65 6e 73  interfaces opens
382a0 20 61 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 20   a [BLOB handle 
382b0 7c 20 68 61 6e 64 6c 65 5d 20 74 6f 20 74 68 65  | handle] to the
382c0 20 42 4c 4f 42 20 6c 6f 63 61 74 65 64 0a 2a 2a   BLOB located.**
382d0 20 69 6e 20 72 6f 77 20 69 52 6f 77 2c 20 63 6f   in row iRow, co
382e0 6c 75 6d 6e 20 7a 43 6f 6c 75 6d 6e 2c 20 74 61  lumn zColumn, ta
382f0 62 6c 65 20 7a 54 61 62 6c 65 20 69 6e 20 64 61  ble zTable in da
38300 74 61 62 61 73 65 20 7a 44 62 3b 0a 2a 2a 20 69  tabase zDb;.** i
38310 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
38320 68 65 20 73 61 6d 65 20 42 4c 4f 42 20 74 68 61  he same BLOB tha
38330 74 20 77 6f 75 6c 64 20 62 65 20 73 65 6c 65 63  t would be selec
38340 74 65 64 20 62 79 3a 0a 2a 2a 0a 2a 2a 20 3c 70  ted by:.**.** <p
38350 72 65 3e 0a 2a 2a 20 20 20 20 20 53 45 4c 45 43  re>.**     SELEC
38360 54 20 7a 43 6f 6c 75 6d 6e 20 46 52 4f 4d 20 7a  T zColumn FROM z
38370 44 62 2e 7a 54 61 62 6c 65 20 57 48 45 52 45 20  Db.zTable WHERE 
38380 5b 72 6f 77 69 64 5d 20 3d 20 69 52 6f 77 3b 0a  [rowid] = iRow;.
38390 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a 2a 0a 2a  ** </pre>)^.**.*
383a0 2a 20 5e 49 66 20 74 68 65 20 66 6c 61 67 73 20  * ^If the flags 
383b0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e  parameter is non
383c0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
383d0 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20 66  BLOB is opened f
383e0 6f 72 20 72 65 61 64 0a 2a 2a 20 61 6e 64 20 77  or read.** and w
383f0 72 69 74 65 20 61 63 63 65 73 73 2e 20 5e 49 66  rite access. ^If
38400 20 69 74 20 69 73 20 7a 65 72 6f 2c 20 74 68 65   it is zero, the
38410 20 42 4c 4f 42 20 69 73 20 6f 70 65 6e 65 64 20   BLOB is opened 
38420 66 6f 72 20 72 65 61 64 20 61 63 63 65 73 73 2e  for read access.
38430 0a 2a 2a 20 5e 49 74 20 69 73 20 6e 6f 74 20 70  .** ^It is not p
38440 6f 73 73 69 62 6c 65 20 74 6f 20 6f 70 65 6e 20  ossible to open 
38450 61 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  a column that is
38460 20 70 61 72 74 20 6f 66 20 61 6e 20 69 6e 64 65   part of an inde
38470 78 20 6f 72 20 70 72 69 6d 61 72 79 20 0a 2a 2a  x or primary .**
38480 20 6b 65 79 20 66 6f 72 20 77 72 69 74 69 6e 67   key for writing
38490 2e 20 5e 49 66 20 5b 66 6f 72 65 69 67 6e 20 6b  . ^If [foreign k
384a0 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 20  ey constraints] 
384b0 61 72 65 20 65 6e 61 62 6c 65 64 2c 20 69 74 20  are enabled, it 
384c0 69 73 20 0a 2a 2a 20 6e 6f 74 20 70 6f 73 73 69  is .** not possi
384d0 62 6c 65 20 74 6f 20 6f 70 65 6e 20 61 20 63 6f  ble to open a co
384e0 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 70 61 72  lumn that is par
384f0 74 20 6f 66 20 61 20 5b 63 68 69 6c 64 20 6b 65  t of a [child ke
38500 79 5d 20 66 6f 72 20 77 72 69 74 69 6e 67 2e 0a  y] for writing..
38510 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
38520 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e 61   the database na
38530 6d 65 20 69 73 20 6e 6f 74 20 74 68 65 20 66 69  me is not the fi
38540 6c 65 6e 61 6d 65 20 74 68 61 74 20 63 6f 6e 74  lename that cont
38550 61 69 6e 73 0a 2a 2a 20 74 68 65 20 64 61 74 61  ains.** the data
38560 62 61 73 65 20 62 75 74 20 72 61 74 68 65 72 20  base but rather 
38570 74 68 65 20 73 79 6d 62 6f 6c 69 63 20 6e 61 6d  the symbolic nam
38580 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
38590 65 20 74 68 61 74 0a 2a 2a 20 61 70 70 65 61 72  e that.** appear
385a0 73 20 61 66 74 65 72 20 74 68 65 20 41 53 20 6b  s after the AS k
385b0 65 79 77 6f 72 64 20 77 68 65 6e 20 74 68 65 20  eyword when the 
385c0 64 61 74 61 62 61 73 65 20 69 73 20 63 6f 6e 6e  database is conn
385d0 65 63 74 65 64 20 75 73 69 6e 67 20 5b 41 54 54  ected using [ATT
385e0 41 43 48 5d 2e 0a 2a 2a 20 5e 46 6f 72 20 74 68  ACH]..** ^For th
385f0 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 20  e main database 
38600 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 62 61  file, the databa
38610 73 65 20 6e 61 6d 65 20 69 73 20 22 6d 61 69 6e  se name is "main
38620 22 2e 0a 2a 2a 20 5e 46 6f 72 20 54 45 4d 50 20  "..** ^For TEMP 
38630 74 61 62 6c 65 73 2c 20 74 68 65 20 64 61 74 61  tables, the data
38640 62 61 73 65 20 6e 61 6d 65 20 69 73 20 22 74 65  base name is "te
38650 6d 70 22 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 20  mp"..**.** ^(On 
38660 73 75 63 63 65 73 73 2c 20 5b 53 51 4c 49 54 45  success, [SQLITE
38670 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
38680 20 61 6e 64 20 74 68 65 20 6e 65 77 20 5b 42 4c   and the new [BL
38690 4f 42 20 68 61 6e 64 6c 65 5d 20 69 73 20 77 72  OB handle] is wr
386a0 69 74 74 65 6e 0a 2a 2a 20 74 6f 20 2a 70 70 42  itten.** to *ppB
386b0 6c 6f 62 2e 20 4f 74 68 65 72 77 69 73 65 20 61  lob. Otherwise a
386c0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
386d0 73 20 72 65 74 75 72 6e 65 64 20 61 6e 64 20 2a  s returned and *
386e0 70 70 42 6c 6f 62 20 69 73 20 73 65 74 0a 2a 2a  ppBlob is set.**
386f0 20 74 6f 20 62 65 20 61 20 6e 75 6c 6c 20 70 6f   to be a null po
38700 69 6e 74 65 72 2e 29 5e 0a 2a 2a 20 5e 54 68 69  inter.)^.** ^Thi
38710 73 20 66 75 6e 63 74 69 6f 6e 20 73 65 74 73 20  s function sets 
38720 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
38730 6e 6e 65 63 74 69 6f 6e 5d 20 65 72 72 6f 72 20  nnection] error 
38740 63 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65  code and message
38750 0a 2a 2a 20 61 63 63 65 73 73 69 62 6c 65 20 76  .** accessible v
38760 69 61 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  ia [sqlite3_errc
38770 6f 64 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ode()] and [sqli
38780 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 61 6e  te3_errmsg()] an
38790 64 20 72 65 6c 61 74 65 64 0a 2a 2a 20 66 75 6e  d related.** fun
387a0 63 74 69 6f 6e 73 2e 20 5e 4e 6f 74 65 20 74 68  ctions. ^Note th
387b0 61 74 20 74 68 65 20 2a 70 70 42 6c 6f 62 20 76  at the *ppBlob v
387c0 61 72 69 61 62 6c 65 20 69 73 20 61 6c 77 61 79  ariable is alway
387d0 73 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 69 6e  s initialized in
387e0 20 61 0a 2a 2a 20 77 61 79 20 74 68 61 74 20 6d   a.** way that m
387f0 61 6b 65 73 20 69 74 20 73 61 66 65 20 74 6f 20  akes it safe to 
38800 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
38810 62 6c 6f 62 5f 63 6c 6f 73 65 28 29 5d 20 6f 6e  blob_close()] on
38820 20 2a 70 70 42 6c 6f 62 0a 2a 2a 20 72 65 67 61