System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 0def544ef56e14e7946c2b852d68bc4a9338570f:


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 31 35 22 0a 23 64 65 66 69 6e 65 20 53  .7.15".#define S
1030: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
1040: 4d 42 45 52 20 33 30 30 37 30 31 35 0a 23 64 65  MBER 3007015.#de
1050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  fine SQLITE_SOUR
1060: 43 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 32  CE_ID      "2012
1070: 2d 31 32 2d 31 30 20 32 32 3a 31 39 3a 31 34 20  -12-10 22:19:14 
1080: 62 64 37 61 65 65 62 36 39 31 66 65 65 36 39 64  bd7aeeb691fee69d
1090: 64 36 61 35 36 32 31 33 38 61 37 61 62 61 38 65  d6a562138a7aba8e
10a0: 38 65 31 39 32 32 37 32 22 0a 0a 2f 2a 0a 2a 2a  8e192272"../*.**
10b0: 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54   CAPI3REF: Run-T
10c0: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
10d0: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b  ion Numbers.** K
10e0: 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33  EYWORDS: sqlite3
10f0: 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65  _version, sqlite
1100: 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a  3_sourceid.**.**
1110: 20 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   These interface
1120: 73 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61  s provide the sa
1130: 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  me information a
1140: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  s the [SQLITE_VE
1150: 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  RSION],.** [SQLI
1160: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
1170: 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  R], and [SQLITE_
1180: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
1190: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73  processor macros
11a0: 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f  .** but are asso
11b0: 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
11c0: 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20  library instead 
11d0: 6f 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69  of the header fi
11e0: 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a  le.  ^(Cautious.
11f0: 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  ** programmers m
1200: 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73  ight include ass
1210: 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73  ert() statements
1220: 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63   in their applic
1230: 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69  ation to.** veri
1240: 66 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72  fy that values r
1250: 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65  eturned by these
1260: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63   interfaces matc
1270: 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a  h the macros in.
1280: 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61  ** the header, a
1290: 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74  nd thus insure t
12a0: 68 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  hat the applicat
12b0: 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c  ion is.** compil
12c0: 65 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67  ed with matching
12d0: 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61   library and hea
12e0: 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a  der files..**.**
12f0: 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1300: 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71  e>.** assert( sq
1310: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1320: 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54  _number()==SQLIT
1330: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1340: 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73   );.** assert( s
1350: 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f  trcmp(sqlite3_so
1360: 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f  urceid(),SQLITE_
1370: 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b  SOURCE_ID)==0 );
1380: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63  .** assert( strc
1390: 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  mp(sqlite3_libve
13a0: 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56  rsion(),SQLITE_V
13b0: 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a  ERSION)==0 );.**
13c0: 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
13d0: 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
13e0: 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  e sqlite3_versio
13f0: 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74  n[] string const
1400: 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ant contains the
1410: 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45   text of [SQLITE
1420: 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63  _VERSION].** mac
1430: 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ro.  ^The sqlite
1440: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66  3_libversion() f
1450: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1460: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
1470: 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74  .** to the sqlit
1480: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
1490: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54  ing constant.  T
14a0: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
14b0: 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74  rsion().** funct
14c0: 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20  ion is provided 
14d0: 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20  for use in DLLs 
14e0: 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20  since DLL users 
14f0: 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68  usually do not h
1500: 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63  ave.** direct ac
1510: 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63  cess to string c
1520: 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20  onstants within 
1530: 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a  the DLL.  ^The.*
1540: 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  * sqlite3_libver
1550: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75  sion_number() fu
1560: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1570: 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20  n integer equal 
1580: 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  to.** [SQLITE_VE
1590: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20  RSION_NUMBER].  
15a0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75  ^The sqlite3_sou
15b0: 72 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e  rceid() function
15c0: 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70   returns .** a p
15d0: 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69  ointer to a stri
15e0: 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73  ng constant whos
15f0: 65 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73  e value is the s
1600: 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b  ame as the .** [
1610: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
1620: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
1630: 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65   macro..**.** Se
1640: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f  e also: [sqlite_
1650: 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b  version()] and [
1660: 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64  sqlite_source_id
1670: 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
1680: 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e  PI SQLITE_EXTERN
1690: 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69   const char sqli
16a0: 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53  te3_version[];.S
16b0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16c0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69  char *sqlite3_li
16d0: 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  bversion(void);.
16e0: 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
16f0: 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73   char *sqlite3_s
1700: 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53  ourceid(void);.S
1710: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1720: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1730: 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a  _number(void);..
1740: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1750: 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79  Run-Time Library
1760: 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74   Compilation Opt
1770: 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73  ions Diagnostics
1780: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1790: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
17a0: 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f  n_used() functio
17b0: 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31  n returns 0 or 1
17c0: 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20   .** indicating 
17d0: 77 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63  whether the spec
17e0: 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73  ified option was
17f0: 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20   defined at .** 
1800: 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e  compile time.  ^
1810: 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66  The SQLITE_ pref
1820: 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65  ix may be omitte
1830: 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f  d from the .** o
1840: 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65  ption name passe
1850: 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  d to sqlite3_com
1860: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1870: 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).  .**.** ^The 
1880: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1890: 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63  ption_get() func
18a0: 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72  tion allows iter
18b0: 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68  ating.** over th
18c0: 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e  e list of option
18d0: 73 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69  s that were defi
18e0: 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ned at compile t
18f0: 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e  ime by.** return
1900: 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d  ing the N-th com
1910: 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e  pile time option
1920: 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20   string.  ^If N 
1930: 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c  is out of range,
1940: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  .** sqlite3_comp
1950: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20  ileoption_get() 
1960: 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
1970: 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51  ointer.  ^The SQ
1980: 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78  LITE_ .** prefix
1990: 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
19a0: 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74   any strings ret
19b0: 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  urned by .** sql
19c0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
19d0: 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20  on_get()..**.** 
19e0: 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65  ^Support for the
19f0: 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63   diagnostic func
1a00: 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f  tions sqlite3_co
1a10: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64  mpileoption_used
1a20: 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65  ().** and sqlite
1a30: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1a40: 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69  get() may be omi
1a50: 74 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69  tted by specifyi
1a60: 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  ng the .** [SQLI
1a70: 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f  TE_OMIT_COMPILEO
1a80: 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74  PTION_DIAGS] opt
1a90: 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74  ion at compile t
1aa0: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ime..**.** See a
1ab0: 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f  lso: SQL functio
1ac0: 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69  ns [sqlite_compi
1ad0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d  leoption_used()]
1ae0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f   and.** [sqlite_
1af0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
1b00: 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f  t()] and the [co
1b10: 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72  mpile_options pr
1b20: 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65  agma]..*/.#ifnde
1b30: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f  f SQLITE_OMIT_CO
1b40: 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47  MPILEOPTION_DIAG
1b50: 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  S.SQLITE_API int
1b60: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
1b70: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73  option_used(cons
1b80: 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65  t char *zOptName
1b90: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
1ba0: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
1bb0: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
1bc0: 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64  get(int N);.#end
1bd0: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
1be0: 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20  EF: Test To See 
1bf0: 49 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49  If The Library I
1c00: 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a  s Threadsafe.**.
1c10: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1c20: 74 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e  threadsafe() fun
1c30: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65  ction returns ze
1c40: 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  ro if and only i
1c50: 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20  f.** SQLite was 
1c60: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75  compiled with mu
1c70: 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74  texing code omit
1c80: 74 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a  ted due to the.*
1c90: 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
1ca0: 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SAFE] compile-ti
1cb0: 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20  me option being 
1cc0: 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20  set to 0..**.** 
1cd0: 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f  SQLite can be co
1ce0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77  mpiled with or w
1cf0: 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20  ithout mutexes. 
1d00: 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51   When.** the [SQ
1d10: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
1d20: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1d30: 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c  macro is 1 or 2,
1d40: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
1d50: 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69  enabled and SQLi
1d60: 74 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  te is threadsafe
1d70: 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b  .  When the.** [
1d80: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d90: 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a  E] macro is 0, .
1da0: 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61  ** the mutexes a
1db0: 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74  re omitted.  Wit
1dc0: 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73  hout the mutexes
1dd0: 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65  , it is not safe
1de0: 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74  .** to use SQLit
1df0: 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66  e concurrently f
1e00: 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  rom more than on
1e10: 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20  e thread..**.** 
1e20: 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73  Enabling mutexes
1e30: 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72   incurs a measur
1e40: 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65  able performance
1e50: 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20   penalty..** So 
1e60: 69 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75  if speed is of u
1e70: 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65  tmost importance
1e80: 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65  , it makes sense
1e90: 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74   to disable.** t
1ea0: 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74  he mutexes.  But
1eb0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66   for maximum saf
1ec0: 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f  ety, mutexes sho
1ed0: 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a  uld be enabled..
1ee0: 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1ef0: 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20  behavior is for 
1f00: 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e  mutexes to be en
1f10: 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  abled..**.** Thi
1f20: 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
1f30: 62 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70  be used by an ap
1f40: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b  plication to mak
1f50: 65 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a  e sure that the.
1f60: 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51  ** version of SQ
1f70: 4c 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20  Lite that it is 
1f80: 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20  linking against 
1f90: 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  was compiled wit
1fa0: 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64  h.** the desired
1fb0: 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20   setting of the 
1fc0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fd0: 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a  FE] macro..**.**
1fe0: 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
1ff0: 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20  only reports on 
2000: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
2010: 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a   mutex setting.*
2020: 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45  * of the [SQLITE
2030: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61  _THREADSAFE] fla
2040: 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  g.  If SQLite is
2050: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
2060: 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  * SQLITE_THREADS
2070: 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e  AFE=1 or =2 then
2080: 20 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61   mutexes are ena
2090: 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
20a0: 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75  but.** can be fu
20b0: 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79  lly or partially
20c0: 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20   disabled using 
20d0: 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  a call to [sqlit
20e0: 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20  e3_config()].** 
20f0: 77 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b  with the verbs [
2100: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
2110: 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51  NGLETHREAD], [SQ
2120: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
2130: 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20  ITHREAD],.** or 
2140: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2150: 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65  UTEX].  ^(The re
2160: 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
2170: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72  e.** sqlite3_thr
2180: 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69  eadsafe() functi
2190: 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68  on shows only th
21a0: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73  e compile-time s
21b0: 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72  etting of.** thr
21c0: 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20  ead safety, not 
21d0: 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61  any run-time cha
21e0: 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74  nges to that set
21f0: 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20  ting made by.** 
2200: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
2210: 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  . In other words
2220: 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2230: 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
2240: 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20  threadsafe().** 
2250: 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20  is unchanged by 
2260: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2270: 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a  _config().)^.**.
2280: 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65  ** See the [thre
2290: 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75  ading mode] docu
22a0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
22b0: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22c0: 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
22d0: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22e0: 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29  threadsafe(void)
22f0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2300: 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
2310: 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a  ection Handle.**
2320: 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61   KEYWORDS: {data
2330: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d  base connection}
2340: 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   {database conne
2350: 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61  ctions}.**.** Ea
2360: 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64  ch open SQLite d
2370: 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65  atabase is repre
2380: 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e  sented by a poin
2390: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
23a0: 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61  ce of.** the opa
23b0: 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61  que structure na
23c0: 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20  med "sqlite3".  
23d0: 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20  It is useful to 
23e0: 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69  think of an sqli
23f0: 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61  te3.** pointer a
2400: 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68  s an object.  Th
2410: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  e [sqlite3_open(
2420: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
2430: 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  n16()], and.** [
2440: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
2450: 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  )] interfaces ar
2460: 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f  e its constructo
2470: 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  rs, and [sqlite3
2480: 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64  _close()].** and
2490: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f   [sqlite3_close_
24a0: 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65  v2()] are its de
24b0: 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72  structors.  Ther
24c0: 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72  e are many other
24d0: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28  .** interfaces (
24e0: 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69  such as.** [sqli
24f0: 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2500: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
2510: 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20  te_function()], 
2520: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2530: 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20  busy_timeout()] 
2540: 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65  to name but thre
2550: 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68  e) that are meth
2560: 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c  ods on an.** sql
2570: 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ite3 object..*/.
2580: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2590: 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a  qlite3 sqlite3;.
25a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25b0: 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20   64-Bit Integer 
25c0: 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Types.** KEYWORD
25d0: 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  S: sqlite_int64 
25e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a  sqlite_uint64.**
25f0: 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72  .** Because ther
2600: 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c  e is no cross-pl
2610: 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70  atform way to sp
2620: 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74  ecify 64-bit int
2630: 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51  eger types.** SQ
2640: 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79  Lite includes ty
2650: 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69  pedefs for 64-bi
2660: 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73  t signed and uns
2670: 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a  igned integers..
2680: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2690: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26a0: 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74  te3_uint64 are t
26b0: 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70  he preferred typ
26c0: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a  e definitions..*
26d0: 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74  * The sqlite_int
26e0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
26f0: 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73  nt64 types are s
2700: 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63  upported for bac
2710: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
2720: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a  ibility only..**
2730: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2740: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
2750: 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  e_int64 types ca
2760: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2770: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
2780: 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34  n -9223372036854
2790: 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33  775808 and +9223
27a0: 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20  372036854775807 
27b0: 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65  inclusive.  ^The
27c0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74  .** sqlite3_uint
27d0: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69  64 and sqlite_ui
27e0: 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73  nt64 types can s
27f0: 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c  tore integer val
2800: 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20  ues .** between 
2810: 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30  0 and +184467440
2820: 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c  73709551615 incl
2830: 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66  usive..*/.#ifdef
2840: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2850: 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c  PE.  typedef SQL
2860: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73  ITE_INT64_TYPE s
2870: 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74  qlite_int64;.  t
2880: 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20  ypedef unsigned 
2890: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
28a0: 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b  E sqlite_uint64;
28b0: 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f  .#elif defined(_
28c0: 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69  MSC_VER) || defi
28d0: 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f  ned(__BORLANDC__
28e0: 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e  ).  typedef __in
28f0: 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  t64 sqlite_int64
2900: 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69  ;.  typedef unsi
2910: 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c  gned __int64 sql
2920: 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73  ite_uint64;.#els
2930: 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67  e.  typedef long
2940: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
2950: 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65  _int64;.  typede
2960: 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20  f unsigned long 
2970: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2980: 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74  uint64;.#endif.t
2990: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e  ypedef sqlite_in
29a0: 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t64 sqlite3_int6
29b0: 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74  4;.typedef sqlit
29c0: 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e_uint64 sqlite3
29d0: 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20  _uint64;../*.** 
29e0: 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72  If compiling for
29f0: 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61   a processor tha
2a00: 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67  t lacks floating
2a10: 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a   point support,.
2a20: 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e  ** substitute in
2a30: 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69  teger for floati
2a40: 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66  ng-point..*/.#if
2a50: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
2a60: 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23  FLOATING_POINT.#
2a70: 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73   define double s
2a80: 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e  qlite3_int64.#en
2a90: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
2aa0: 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44  REF: Closing A D
2ab0: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2ac0: 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  on.**.** ^The sq
2ad0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e  lite3_close() an
2ae0: 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  d sqlite3_close_
2af0: 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72  v2() routines ar
2b00: 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a  e destructors.**
2b10: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
2b20: 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43  3] object..** ^C
2b30: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2b40: 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69  close() and sqli
2b50: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72  te3_close_v2() r
2b60: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
2b70: 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  if.** the [sqlit
2b80: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75  e3] object is su
2b90: 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72  ccessfully destr
2ba0: 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73  oyed and all ass
2bb0: 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75  ociated.** resou
2bc0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2bd0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ated..**.** ^If 
2be0: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2bf0: 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63  nection is assoc
2c00: 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e  iated with unfin
2c10: 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a  alized prepared.
2c20: 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72  ** statements or
2c30: 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69   unfinished sqli
2c40: 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63  te3_backup objec
2c50: 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ts then sqlite3_
2c60: 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20  close().** will 
2c70: 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61  leave the databa
2c80: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
2c90: 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  en and return [S
2ca0: 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20  QLITE_BUSY]..** 
2cb0: 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  ^If sqlite3_clos
2cc0: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2cd0: 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65   with unfinalize
2ce0: 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  d prepared state
2cf0: 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66  ments.** and unf
2d00: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
2d10: 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68  backups, then th
2d20: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2d30: 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a  ction becomes.**
2d40: 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f   an unusable "zo
2d50: 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c  mbie" which will
2d60: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
2d70: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68  e deallocated wh
2d80: 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70  en the.** last p
2d90: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2da0: 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f  t is finalized o
2db0: 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74  r the last sqlit
2dc0: 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20  e3_backup is.** 
2dd0: 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73  finished.  The s
2de0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2df0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
2e00: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
2e10: 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e  with.** host lan
2e20: 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20  guages that are 
2e30: 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65  garbage collecte
2e40: 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65  d, and where the
2e50: 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a   order in which.
2e60: 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61  ** destructors a
2e70: 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62  re called is arb
2e80: 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70  itrary..**.** Ap
2e90: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
2ea0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  d [sqlite3_final
2eb0: 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20  ize | finalize] 
2ec0: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
2ed0: 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73  atements],.** [s
2ee0: 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73  qlite3_blob_clos
2ef0: 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b  e | close] all [
2f00: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61  BLOB handles], a
2f10: 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nd .** [sqlite3_
2f20: 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20  backup_finish | 
2f30: 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c  finish] all [sql
2f40: 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a  ite3_backup] obj
2f50: 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a  ects associated.
2f60: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c  ** with the [sql
2f70: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69  ite3] object pri
2f80: 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67  or to attempting
2f90: 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62   to close the ob
2fa0: 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71  ject.  ^If.** sq
2fb0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 69 73  lite3_close() is
2fc0: 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64 61   called on a [da
2fd0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2fe0: 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68 61  n] that still ha
2ff0: 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e 67  s.** outstanding
3000: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
3010: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
3020: 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a  ndles], and/or.*
3030: 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  * [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e 20  p] objects then 
3050: 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  it returns SQLIT
3060: 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65 61  E_OK but the dea
3070: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
3080: 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65 66  resources is def
3090: 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c 20  erred until all 
30a0: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
30b0: 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e  ents], [BLOB han
30c0: 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73  dles],.** and [s
30d0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
30e0: 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f 20  bjects are also 
30f0: 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a  destroyed..**.**
3100: 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65 33   ^If an [sqlite3
3110: 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73 74  ] object is dest
3120: 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74 72  royed while a tr
3130: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
3140: 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61  n,.** the transa
3150: 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74  ction is automat
3160: 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61  ically rolled ba
3170: 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20  ck..**.** The C 
3180: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
3190: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20  lite3_close(C)] 
31a0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
31b0: 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75 73  se_v2(C)].** mus
31c0: 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e 55  t be either a NU
31d0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f 72  LL.** pointer or
31e0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
31f0: 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62 74  ject pointer obt
3200: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3210: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
3220: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
3230: 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  )], or.** [sqlit
3240: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61  e3_open_v2()], a
3250: 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73 6c  nd not previousl
3260: 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61  y closed..** ^Ca
3270: 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6c  lling sqlite3_cl
3280: 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ose() or sqlite3
3290: 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74 68  _close_v2() with
32a0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
32b0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  ** argument is a
32c0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
32d0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
32e0: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
32f0: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
3300: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
3310: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69  e3_close_v2(sqli
3320: 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68  te3*);../*.** Th
3330: 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c  e type for a cal
3340: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a  lback function..
3350: 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61 63  ** This is legac
3360: 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  y and deprecated
3370: 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65  .  It is include
3380: 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  d for historical
3390: 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
33a0: 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63  y and is not doc
33b0: 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65  umented..*/.type
33c0: 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65  def int (*sqlite
33d0: 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  3_callback)(void
33e0: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68  *,int,char**, ch
33f0: 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ar**);../*.** CA
3400: 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70  PI3REF: One-Step
3410: 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e   Query Execution
3420: 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a   Interface.**.**
3430: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   The sqlite3_exe
3440: 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  c() interface is
3450: 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77   a convenience w
3460: 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a  rapper around.**
3470: 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
3480: 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  e_v2()], [sqlite
3490: 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b  3_step()], and [
34a0: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
34b0: 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c  ()],.** that all
34c0: 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ows an applicati
34d0: 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70  on to run multip
34e0: 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66  le statements of
34f0: 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20   SQL.** without 
3500: 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20  having to use a 
3510: 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a  lot of C code. .
3520: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
3530: 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66  e3_exec() interf
3540: 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72  ace runs zero or
3550: 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f   more UTF-8 enco
3560: 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  ded,.** semicolo
3570: 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20 73  n-separate SQL s
3580: 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64  tatements passed
3590: 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72   into its 2nd ar
35a0: 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68  gument,.** in th
35b0: 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65  e context of the
35c0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
35d0: 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e  ction] passed in
35e0: 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61   as its 1st.** a
35f0: 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68  rgument.  ^If th
3600: 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
3610: 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61  ion of the 3rd a
3620: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3630: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3640: 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69  not NULL, then i
3650: 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72  t is invoked for
3660: 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77   each result row
3670: 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f  .** coming out o
3680: 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64 20  f the evaluated 
3690: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20  SQL statements. 
36a0: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
36b0: 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  nt to.** sqlite3
36c0: 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61 79  _exec() is relay
36d0: 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68  ed through to th
36e0: 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f  e 1st argument o
36f0: 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61  f each.** callba
3700: 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20  ck invocation.  
3710: 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
3720: 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69   pointer to sqli
3730: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
3740: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63   NULL, then no c
3750: 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20  allback is ever 
3760: 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75  invoked and resu
3770: 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69  lt rows are.** i
3780: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  gnored..**.** ^I
3790: 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  f an error occur
37a0: 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  s while evaluati
37b0: 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ng the SQL state
37c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
37d0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
37e0: 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74  c(), then execut
37f0: 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  ion of the curre
3800: 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f  nt statement sto
3810: 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71  ps and.** subseq
3820: 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20  uent statements 
3830: 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49  are skipped.  ^I
3840: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3850: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3860: 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20  xec().** is not 
3870: 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72  NULL then any er
3880: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20 77  ror message is w
3890: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
38a0: 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ry obtained.** f
38b0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
38c0: 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65  loc()] and passe
38d0: 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74  d back through t
38e0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
38f0: 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65  ..** To avoid me
3900: 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20  mory leaks, the 
3910: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
3920: 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ld invoke [sqlit
3930: 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e  e3_free()].** on
3940: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3950: 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
3960: 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68 20  through the 5th 
3970: 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20  parameter of.** 
3980: 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  of sqlite3_exec(
3990: 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72 6f  ) after the erro
39a0: 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
39b0: 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65   is no longer ne
39c0: 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eded..** ^If the
39d0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
39e0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
39f0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
3a00: 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63   no errors.** oc
3a10: 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  cur, then sqlite
3a20: 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74 68  3_exec() sets th
3a30: 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73  e pointer in its
3a40: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   5th parameter t
3a50: 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65  o.** NULL before
3a60: 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a   returning..**.*
3a70: 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33  * ^If an sqlite3
3a80: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3a90: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
3aa0: 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  o, the sqlite3_e
3ab0: 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  xec().** routine
3ac0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
3ad0: 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e  ABORT without in
3ae0: 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62  voking the callb
3af0: 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a  ack again and.**
3b00: 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67   without running
3b10: 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
3b20: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
3b30: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61  **.** ^The 2nd a
3b40: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
3b50: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61  qlite3_exec() ca
3b60: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3b70: 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
3b80: 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
3b90: 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65  he result.  ^The
3ba0: 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f   3rd argument to
3bb0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3bc0: 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  c().** callback 
3bd0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3be0: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3bf0: 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69  gs obtained as i
3c00: 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  f from.** [sqlit
3c10: 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
3c20: 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20  ], one for each 
3c30: 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20  column.  ^If an 
3c40: 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20  element of a.** 
3c50: 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55  result row is NU
3c60: 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72  LL then the corr
3c70: 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67  esponding string
3c80: 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65   pointer for the
3c90: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63  .** sqlite3_exec
3ca0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  () callback is a
3cb0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
3cc0: 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e  ^The 4th argumen
3cd0: 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69  t to the.** sqli
3ce0: 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62  te3_exec() callb
3cf0: 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20  ack is an array 
3d00: 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  of pointers to s
3d10: 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61 63  trings where eac
3d20: 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65  h.** entry repre
3d30: 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f  sents the name o
3d40: 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  f corresponding 
3d50: 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73  result column as
3d60: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3d70: 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
3d80: 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_name()]..**.**
3d90: 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61 72   ^If the 2nd par
3da0: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3db0: 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e 55  3_exec() is a NU
3dc0: 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f  LL pointer, a po
3dd0: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65  inter.** to an e
3de0: 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20  mpty string, or 
3df0: 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63  a pointer that c
3e00: 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69  ontains only whi
3e10: 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a  tespace and/or .
3e20: 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c  ** SQL comments,
3e30: 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61   then no SQL sta
3e40: 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c  tements are eval
3e50: 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64 61  uated and the da
3e60: 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74  tabase.** is not
3e70: 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20   changed..**.** 
3e80: 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a  Restrictions:.**
3e90: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
3ea0: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3eb0: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
3ec0: 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65  t the 1st parame
3ed0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3ee0: 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73  xec().**      is
3ef0: 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65   a valid and ope
3f00: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
3f10: 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e  ection]..** <li>
3f20: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f30: 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
3f40: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3f50: 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20  tion] specified 
3f60: 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 31  by.**      the 1
3f70: 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
3f80: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77  sqlite3_exec() w
3f90: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65  hile sqlite3_exe
3fa0: 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  c() is running..
3fb0: 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c  ** <li> The appl
3fc0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
3fd0: 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c 20   modify the SQL 
3fe0: 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 70  statement text p
3ff0: 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20 20  assed into.**   
4000: 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d     the 2nd param
4010: 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
4020: 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c  exec() while sql
4030: 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 72  ite3_exec() is r
4040: 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e  unning..** </ul>
4050: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
4060: 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  nt sqlite3_exec(
4070: 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20  .  sqlite3*,    
4080: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4090: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
40a0: 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
40b0: 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
40c0: 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20  r *sql,         
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
40f0: 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e  valuated */.  in
4100: 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f  t (*callback)(vo
4110: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63  id*,int,char**,c
4120: 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c  har**),  /* Call
4130: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  back function */
4140: 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20  .  void *,      
4150: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
4170: 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f   1st argument to
4180: 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63   callback */.  c
4190: 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20  har **errmsg    
41a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41b0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72            /* Err
41c0: 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
41d0: 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  ere */.);../*.**
41e0: 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c   CAPI3REF: Resul
41f0: 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f  t Codes.** KEYWO
4200: 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b  RDS: SQLITE_OK {
4210: 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72  error code} {err
4220: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4230: 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63  WORDS: {result c
4240: 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64  ode} {result cod
4250: 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53  es}.**.** Many S
4260: 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20  QLite functions 
4270: 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65  return an intege
4280: 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72  r result code fr
4290: 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e  om the set shown
42a0: 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65  .** here in orde
42b0: 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73 75  r to indicate su
42c0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
42d0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
42e0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
42f0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
4300: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4310: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
4320: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
4330: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
4340: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
4350: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
4360: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
4370: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
4380: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
4390: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
43a0: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
43b0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
43c0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
43d0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
43e0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
43f0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
4400: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
4410: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
4420: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
4430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4440: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
4450: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
4460: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
4470: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
4480: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
4490: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
44a0: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
44b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
44c0: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
44d0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
44e0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
44f0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
4500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4510: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4520: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4530: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4540: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4550: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4560: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4570: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4580: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4590: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
45a0: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
45b0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
45c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
45d0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
45e0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
45f0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
4600: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4610: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4620: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4630: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4640: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4650: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4660: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4670: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4680: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4690: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
46a0: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
46b0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
46c0: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
46d0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
46e0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
46f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4700: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4710: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4720: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4730: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4740: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4750: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4760: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4770: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4780: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4790: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
47a0: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
47b0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
47c0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
47d0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
47e0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
47f0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
4800: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4810: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4820: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4830: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4840: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4850: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4860: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4870: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4880: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4890: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
48a0: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
48b0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
48c0: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
48d0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
48e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
48f0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
4900: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4910: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4920: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4930: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4940: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4950: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4960: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4970: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4980: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4990: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
49a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
49b0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
49c0: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
49d0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
49e0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
49f0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
4a00: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4a10: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4a20: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4a30: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4a40: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4a50: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4a60: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4a70: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4a80: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4a90: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4aa0: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
4ab0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
4ac0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
4ad0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
4ae0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
4af0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
4b00: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4b10: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4b20: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b30: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b40: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b50: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b60: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b70: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b80: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b90: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4ba0: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4bb0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4bc0: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4bd0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4be0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bf0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4c00: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4c10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4c20: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c40: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c50: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c60: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c70: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c80: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c90: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4ca0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4cb0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4cc0: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4cd0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4ce0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cf0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4d00: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4d10: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4d20: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d30: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d40: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d50: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d60: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d70: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d80: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d90: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4da0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4db0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4dc0: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4dd0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4de0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4df0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4e00: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4e10: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4e20: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e30: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e40: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e50: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e60: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e70: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e80: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e90: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4ea0: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4eb0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4ec0: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ed0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4ee0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ef0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4f00: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4f10: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4f20: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f30: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4f40: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4f50: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4f60: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4f70: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4f80: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4f90: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4fa0: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4fb0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4fc0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4fd0: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4fe0: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4ff0: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
5000: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
5010: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
5020: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5030: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
5040: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5050: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
5060: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5070: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
5080: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
5090: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
50a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
50b0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
50c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50d0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
50e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
50f0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
5100: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5110: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
5120: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5130: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
5140: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5150: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
5160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5170: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
5180: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5190: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
51a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51b0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
51c0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51d0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
51e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
51f0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5200: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5210: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5220: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5230: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5240: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5250: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5260: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5270: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5280: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5290: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
52a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52b0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
52c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52d0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
52e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52f0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5300: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5310: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5320: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5330: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5340: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5350: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5370: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5380: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
5390: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
53a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53b0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
53c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53d0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
53e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53f0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5400: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5410: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5420: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5430: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5440: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5450: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5460: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5470: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5480: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5490: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
54a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54b0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
54c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54d0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
54e0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
54f0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5500: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5510: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5520: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5530: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5540: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5550: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5560: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5570: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5580: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5590: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
55a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
55b0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
55c0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
55d0: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
55e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
55f0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
5600: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
5610: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
5620: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5630: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5640: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5650: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5670: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5680: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5690: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
56a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
56b0: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
56c0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
56d0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
56e0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56f0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
5700: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5710: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
5720: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5730: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5740: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5750: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
5760: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5770: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
5780: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
5790: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
57a0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
57b0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
57c0: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
57d0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
57e0: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
57f0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
5800: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
5810: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
5820: 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (2<<8))../*.** C
5830: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5840: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5850: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
5860: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
5870: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
5880: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
5890: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
58a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
58b0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
58c0: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
58d0: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
58e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
58f0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5900: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5910: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5920: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5930: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5940: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5950: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5960: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
5970: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5980: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
5990: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
59a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
59b0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
59c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
59d0: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
59e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
59f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a00: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5a10: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5a20: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
5a30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a40: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5a50: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5a60: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
5a70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5a80: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
5a90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5aa0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
5ab0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ac0: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
5ad0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5ae0: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
5af0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5b00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b10: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5b20: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5b30: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5b40: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5b50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5b60: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5b70: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5b80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5b90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ba0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5bb0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5bc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5bd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5be0: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5bf0: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
5c00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5c10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c20: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5c30: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
5c40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5c50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c60: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5c70: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
5c80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5c90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ca0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
5cb0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
5cc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5cd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ce0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
5cf0: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
5d00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5d10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d20: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
5d30: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
5d40: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5d50: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d60: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d70: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
5d80: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
5d90: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5da0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5db0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5dc0: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
5dd0: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
5de0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5df0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5e00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e10: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
5e20: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
5e30: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
5e40: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5e50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e60: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
5e70: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
5e80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5e90: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
5ea0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5eb0: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
5ec0: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
5ed0: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
5ee0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
5ef0: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
5f00: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
5f10: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
5f20: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
5f30: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
5f40: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
5f50: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
5f60: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
5f70: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
5f80: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
5f90: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
5fa0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
5fb0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
5fc0: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
5fd0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
5fe0: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
5ff0: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6000: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6010: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6020: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
6030: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
6040: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6050: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6060: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
6070: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
6080: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
6090: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
60a0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
60b0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
60c0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
60d0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
60e0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
60f0: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6100: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6110: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6120: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6130: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6140: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6150: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
6160: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
6170: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
6180: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
6190: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
61a0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
61b0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
61c0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
61d0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
61e0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
61f0: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6200: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6210: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6220: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6230: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6240: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6250: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
6260: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
6270: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
6280: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
6290: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
62a0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
62b0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
62c0: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
62d0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
62e0: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
62f0: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6300: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6310: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6320: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6330: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6340: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6350: 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66  changed..*/.#def
6360: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6370: 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20  _ATOMIC         
6380: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6390: 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  01.#define SQLIT
63a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31  E_IOCAP_ATOMIC51
63b0: 32 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  2              0
63c0: 78 30 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e  x00000002.#defin
63d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
63e0: 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20  TOMIC1K         
63f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
6400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6410: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20  IOCAP_ATOMIC2K  
6420: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6430: 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20  0000008.#define 
6440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6450: 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20 20 20  MIC4K           
6460: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 0a 23      0x00000010.#
6470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6480: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20  CAP_ATOMIC8K    
6490: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
64a0: 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51  00020.#define SQ
64b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
64c0: 43 31 36 4b 20 20 20 20 20 20 20 20 20 20 20 20  C16K            
64d0: 20 20 30 78 30 30 30 30 30 30 34 30 0a 23 64 65    0x00000040.#de
64e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
64f0: 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20  P_ATOMIC32K     
6500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6510: 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  080.#define SQLI
6520: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36  TE_IOCAP_ATOMIC6
6530: 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  4K              
6540: 30 78 30 30 30 30 30 31 30 30 0a 23 64 65 66 69  0x00000100.#defi
6550: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6560: 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20  SAFE_APPEND     
6570: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
6580: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6590: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
65a0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78  L             0x
65b0: 30 30 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65  00000400.#define
65c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e   SQLITE_IOCAP_UN
65d0: 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f  DELETABLE_WHEN_O
65e0: 50 45 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a  PEN  0x00000800.
65f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6600: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6610: 56 45 52 57 52 49 54 45 20 20 20 20 30 78 30 30  VERWRITE    0x00
6620: 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  001000../*.** CA
6630: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6640: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6650: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
6660: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
6670: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6680: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
6690: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
66a0: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
66b0: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
66c0: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
66d0: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
66e0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
66f0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6700: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6710: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6720: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6730: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6740: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6750: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
6760: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6770: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
6780: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
6790: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
67a0: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
67b0: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
67c0: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
67d0: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
67e0: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
67f0: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6800: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6810: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6820: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6830: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6840: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6850: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6860: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6870: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6880: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6890: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
68a0: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
68b0: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
68c0: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
68d0: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
68e0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
68f0: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
6900: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6910: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
6920: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6930: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6940: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6950: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
6960: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
6970: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
6980: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
6990: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
69a0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
69b0: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
69c0: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
69d0: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
69e0: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
69f0: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
6a00: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
6a10: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
6a20: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6a30: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
6a40: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
6a50: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6a60: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
6a70: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6a80: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
6a90: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
6aa0: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
6ab0: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
6ac0: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
6ad0: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
6ae0: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
6af0: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
6b00: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
6b10: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
6b20: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6b30: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6b40: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
6b50: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
6b60: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
6b70: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
6b80: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
6b90: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
6ba0: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
6bb0: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
6bc0: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
6bd0: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
6be0: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
6bf0: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
6c00: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
6c10: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
6c20: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
6c30: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6c40: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
6c50: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
6c60: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
6c70: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
6c80: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
6c90: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
6ca0: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
6cb0: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
6cc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
6cd0: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
6ce0: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
6cf0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6d00: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
6d10: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
6d20: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
6d30: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
6d40: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
6d50: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
6d60: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
6d70: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
6d80: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
6d90: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
6da0: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
6db0: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
6dc0: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
6dd0: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
6de0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
6df0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
6e00: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
6e10: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
6e20: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
6e30: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
6e40: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
6e50: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
6e60: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
6e70: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
6e80: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
6e90: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
6ea0: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
6eb0: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
6ec0: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
6ed0: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
6ee0: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
6ef0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6f00: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
6f10: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
6f20: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
6f30: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
6f40: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
6f50: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
6f60: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
6f70: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
6f80: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
6f90: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
6fa0: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
6fb0: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
6fc0: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
6fd0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
6fe0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
6ff0: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
7000: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7010: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
7020: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
7030: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
7040: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
7050: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
7060: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
7070: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
7080: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
7090: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
70a0: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
70b0: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
70c0: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
70d0: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
70e0: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
70f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7100: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7110: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7120: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7130: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
7140: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
7150: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
7160: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
7170: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
7180: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
7190: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
71a0: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
71b0: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
71c0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
71d0: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
71e0: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
71f0: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7200: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7210: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7220: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
7230: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
7240: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
7250: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
7260: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
7270: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
7280: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
7290: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
72a0: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
72b0: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
72c0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
72d0: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
72e0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
72f0: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7300: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7310: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7320: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
7330: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
7340: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
7350: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
7360: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
7370: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
7380: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
7390: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
73a0: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
73b0: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
73c0: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
73d0: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
73e0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
73f0: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7400: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7410: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7420: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
7430: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
7440: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
7450: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7460: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
7470: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
7480: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7490: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
74a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
74b0: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
74c0: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
74d0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
74e0: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
74f0: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7500: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7510: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7520: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
7530: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
7540: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
7550: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
7560: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
7570: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
7580: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
7590: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
75a0: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
75b0: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
75c0: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
75d0: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
75e0: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
75f0: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7600: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7610: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7620: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7630: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7640: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7650: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
7660: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
7670: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
7680: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
7690: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
76a0: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
76b0: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
76c0: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
76d0: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
76e0: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
76f0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7700: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7710: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7720: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7730: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7740: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7750: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
7760: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
7770: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
7780: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
7790: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
77a0: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
77b0: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
77c0: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
77d0: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
77e0: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
77f0: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7800: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7810: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7820: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7830: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7840: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7850: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
7860: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
7870: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
7880: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
7890: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
78a0: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
78b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
78c0: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
78d0: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
78e0: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
78f0: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
7900: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
7910: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
7920: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7930: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
7940: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
7950: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
7960: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
7970: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7980: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
7990: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
79a0: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
79b0: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
79c0: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
79d0: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
79e0: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
79f0: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
7a00: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
7a10: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
7a20: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
7a30: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
7a40: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
7a50: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
7a60: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
7a70: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
7a80: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
7a90: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
7aa0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
7ab0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
7ac0: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
7ad0: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
7ae0: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
7af0: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
7b00: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
7b10: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
7b20: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7b30: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7b40: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
7b50: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
7b60: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
7b70: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7b80: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
7b90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ba0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
7bb0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7bc0: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
7bd0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7be0: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
7bf0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7c00: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
7c10: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7c20: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
7c30: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7c40: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
7c50: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
7c60: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
7c70: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7c80: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
7c90: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
7ca0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7cb0: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
7cc0: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
7cd0: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
7ce0: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7cf0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
7d00: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
7d10: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
7d20: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
7d30: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
7d40: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
7d50: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
7d60: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
7d70: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
7d80: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
7d90: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
7da0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
7db0: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
7dc0: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
7dd0: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
7de0: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
7df0: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
7e00: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
7e10: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
7e20: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
7e30: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
7e40: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
7e50: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
7e60: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
7e70: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
7e80: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
7e90: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
7ea0: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
7eb0: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
7ec0: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
7ed0: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
7ee0: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
7ef0: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
7f00: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
7f10: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
7f20: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
7f30: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
7f40: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
7f50: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
7f60: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
7f70: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
7f80: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
7f90: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
7fa0: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7fb0: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
7fc0: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
7fd0: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
7fe0: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
7ff0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
8000: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
8010: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8020: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
8030: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
8040: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
8050: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
8060: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8070: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
8080: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
8090: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
80a0: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
80b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
80c0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
80d0: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
80e0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
80f0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8100: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
8110: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8120: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
8130: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
8140: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
8150: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
8160: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
8170: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8180: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8190: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
81a0: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
81b0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
81c0: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
81d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
81e0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
81f0: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
8200: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8210: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
8220: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
8230: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
8240: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
8250: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
8260: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
8270: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8280: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
8290: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
82a0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
82b0: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
82c0: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
82d0: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
82e0: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
82f0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
8300: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
8310: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
8320: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
8330: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
8340: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
8350: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
8360: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
8370: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
8380: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8390: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
83a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
83b0: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
83c0: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
83d0: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
83e0: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20  rsion 2 */.  /* 
83f0: 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f  Additional metho
8400: 64 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ds may be added 
8410: 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
8420: 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  es */.};../*.** 
8430: 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61  CAPI3REF: Standa
8440: 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20  rd File Control 
8450: 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  Opcodes.**.** Th
8460: 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
8470: 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65  tants are opcode
8480: 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43  s for the xFileC
8490: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a  ontrol method.**
84a0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
84b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
84c0: 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20  ect and for the 
84d0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
84e0: 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65  ntrol()].** inte
84f0: 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rface..**.** The
8500: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
8510: 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65  OCKSTATE] opcode
8520: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
8530: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
8540: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
8550: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
8560: 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20  method to write 
8570: 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61 74  the current stat
8580: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b  e of.** the lock
8590: 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45   (one of [SQLITE
85a0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51  _LOCK_NONE], [SQ
85b0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
85c0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f  ],.** [SQLITE_LO
85d0: 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53  CK_RESERVED], [S
85e0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
85f0: 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  NG], or [SQLITE_
8600: 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29  LOCK_EXCLUSIVE])
8610: 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65  .** into an inte
8620: 67 65 72 20 74 68 61 74 20 74 68 65 20 70 41 72  ger that the pAr
8630: 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74  g argument point
8640: 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62  s to. This capab
8650: 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64  ility.** is used
8660: 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20   during testing 
8670: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
8680: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
8690: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a  hen SQLITE_TEST.
86a0: 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a  ** is defined..*
86b0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b  * <ul>.** <li>[[
86c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a  SQLITE_FCNTL_SIZ
86d0: 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20  E_HINT]].** The 
86e0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49  [SQLITE_FCNTL_SI
86f0: 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20  ZE_HINT] opcode 
8700: 69 73 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  is used by SQLit
8710: 65 20 74 6f 20 67 69 76 65 20 74 68 65 20 56 46  e to give the VF
8720: 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e  S.** layer a hin
8730: 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74  t of how large t
8740: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8750: 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65   will grow to be
8760: 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63   during the.** c
8770: 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69  urrent transacti
8780: 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69  on.  This hint i
8790: 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64  s not guaranteed
87a0: 20 74 6f 20 62 65 20 61 63 63 75 72 61 74 65 20   to be accurate 
87b0: 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74  but it.** is oft
87c0: 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75  en close.  The u
87d0: 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69  nderlying VFS mi
87e0: 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72  ght choose to pr
87f0: 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61  eallocate databa
8800: 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65  se.** file space
8810: 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68   based on this h
8820: 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  int in order to 
8830: 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74  help writes to t
8840: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66  he database.** f
8850: 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a  ile run faster..
8860: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8870: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
8880: 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  IZE]].** The [SQ
8890: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
88a0: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
88b0: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
88c0: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
88d0: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
88e0: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
88f0: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
8900: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
8910: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
8920: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
8930: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
8940: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
8950: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
8960: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
8970: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
8980: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
8990: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
89a0: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
89b0: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
89c0: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
89d0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
89e0: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
89f0: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
8a00: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
8a10: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
8a20: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
8a30: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
8a40: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
8a50: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
8a60: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8a70: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
8a80: 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ER]].** The [SQL
8a90: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
8aa0: 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69  OINTER] opcode i
8ab0: 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  s used to obtain
8ac0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
8ad0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
8ae0: 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63  le] object assoc
8af0: 69 61 74 65 64 20 77 69 74 68 20 61 20 70 61 72  iated with a par
8b00: 74 69 63 75 6c 61 72 20 64 61 74 61 62 61 73 65  ticular database
8b10: 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  .** connection. 
8b20: 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65   See the [sqlite
8b30: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8b40: 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
8b50: 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
8b60: 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
8b70: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8b80: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
8b90: 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20  TTED]].** ^(The 
8ba0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
8bb0: 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f  NC_OMITTED] opco
8bc0: 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64 20  de is generated 
8bd0: 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a  internally by.**
8be0: 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74   SQLite and sent
8bf0: 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e   to all VFSes in
8c00: 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c   place of a call
8c10: 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65   to the xSync me
8c20: 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65  thod.** when the
8c30: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
8c40: 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41  tion has [PRAGMA
8c50: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65   synchronous] se
8c60: 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53  t to OFF.)^.** S
8c70: 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  ome specialized 
8c80: 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73 20  VFSes need this 
8c90: 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20  signal in order 
8ca0: 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65  to operate corre
8cb0: 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52  ctly.** when [PR
8cc0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
8cd0: 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72   | PRAGMA synchr
8ce0: 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65  onous=OFF] is se
8cf0: 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20  t, but most .** 
8d00: 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65  VFSes do not nee
8d10: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e  d this signal an
8d20: 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c  d should silentl
8d30: 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70  y ignore this op
8d40: 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  code..** Applica
8d50: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
8d60: 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
8d70: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77  ile_control()] w
8d80: 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f  ith this.** opco
8d90: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
8da0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ay disrupt the o
8db0: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
8dc0: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
8dd0: 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71  s.** that do req
8de0: 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a  uire it.  .**.**
8df0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
8e00: 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54  NTL_WIN32_AV_RET
8e10: 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  RY]].** ^The [SQ
8e20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
8e30: 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64  _AV_RETRY] opcod
8e40: 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  e is used to con
8e50: 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63  figure automatic
8e60: 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73  .** retry counts
8e70: 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66   and intervals f
8e80: 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20  or certain disk 
8e90: 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66  I/O operations f
8ea0: 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77  or the.** window
8eb0: 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72  s [VFS] in order
8ec0: 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75   to provide robu
8ed0: 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72  stness in the pr
8ee0: 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74  esence of.** ant
8ef0: 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73  i-virus programs
8f00: 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74  .  By default, t
8f10: 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77  he windows VFS w
8f20: 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72  ill retry file r
8f30: 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69  ead,.** file wri
8f40: 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c  te, and file del
8f50: 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75  ete operations u
8f60: 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77  p to 10 times, w
8f70: 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f  ith a delay.** o
8f80: 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  f 25 millisecond
8f90: 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69 72  s before the fir
8fa0: 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69 74  st retry and wit
8fb0: 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72  h the delay incr
8fc0: 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20  easing.** by an 
8fd0: 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69  additional 25 mi
8fe0: 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20  lliseconds with 
8ff0: 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74 20  each subsequent 
9000: 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20  retry.  This.** 
9010: 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68  opcode allows th
9020: 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28  ese two values (
9030: 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20 32  10 retries and 2
9040: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  5 milliseconds o
9050: 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62  f delay).** to b
9060: 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65  e adjusted.  The
9070: 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e   values are chan
9080: 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61  ged for all data
9090: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
90a0: 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73  .** within the s
90b0: 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68  ame process.  Th
90c0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  e argument is a 
90d0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72  pointer to an ar
90e0: 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e  ray of two.** in
90f0: 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68 65  tegers where the
9100: 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20 69   first integer i
9110: 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20 63   the new retry c
9120: 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63  ount and the sec
9130: 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69  ond.** integer i
9140: 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66  s the delay.  If
9150: 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72 20   either integer 
9160: 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
9170: 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a  n the setting.**
9180: 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20   is not changed 
9190: 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65 20  but instead the 
91a0: 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
91b0: 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20 77  hat setting is w
91c0: 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74  ritten.** into t
91d0: 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20  he array entry, 
91e0: 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72  allowing the cur
91f0: 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74 69  rent retry setti
9200: 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74  ngs to be.** int
9210: 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20  errogated.  The 
9220: 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65  zDbName paramete
9230: 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  r is ignored..**
9240: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
9250: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9260: 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  AL]].** ^The [SQ
9270: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9280: 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69  ST_WAL] opcode i
9290: 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72  s used to set or
92a0: 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65   query the.** pe
92b0: 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20  rsistent [WAL | 
92c0: 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d  Write Ahead Log]
92d0: 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65   setting.  By de
92e0: 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c  fault, the auxil
92f0: 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68  iary.** write ah
9300: 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72  ead log and shar
9310: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
9320: 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63  used for transac
9330: 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  tion control.** 
9340: 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  are automaticall
9350: 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74  y deleted when t
9360: 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63  he latest connec
9370: 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tion to the data
9380: 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20  base.** closes. 
9390: 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73 74   Setting persist
93a0: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75  ent WAL mode cau
93b0: 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20  ses those files 
93c0: 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65 72  to persist after
93d0: 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73  .** close.  Pers
93e0: 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73  isting the files
93f0: 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20   is useful when 
9400: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73 20  other processes 
9410: 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68  that do not.** h
9420: 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69 73  ave write permis
9430: 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65  sion on the dire
9440: 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67  ctory containing
9450: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
9460: 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65  le want.** to re
9470: 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ad the database 
9480: 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c  file, as the WAL
9490: 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f   and shared memo
94a0: 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78  ry files must ex
94b0: 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ist.** in order 
94c0: 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65  for the database
94d0: 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e   to be readable.
94e0: 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
94f0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
9500: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9510: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
9520: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
9530: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
9540: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
9550: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
9560: 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73 74   disable persist
9570: 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20  ent WAL mode or 
9580: 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73  1 to enable pers
9590: 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f  istent.** WAL mo
95a0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
95b0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
95c0: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
95d0: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
95e0: 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73  nt.** WAL persis
95f0: 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a  tence setting..*
9600: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9610: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
9620: 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a  E_OVERWRITE]].**
9630: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
9640: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9650: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
9660: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9670: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9680: 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72  ersistent "power
9690: 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20  safe-overwrite" 
96a0: 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e  or "PSOW" settin
96b0: 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65 74  g.  The PSOW set
96c0: 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ting.** determin
96d0: 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49  es the [SQLITE_I
96e0: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
96f0: 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66  VERWRITE] bit of
9700: 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43   the.** xDeviceC
9710: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
9720: 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72  ethods. The four
9730: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
9740: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9750: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
9760: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
9770: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
9780: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
9790: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
97a0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a  s 0 to disable z
97b0: 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20  ero-damage mode 
97c0: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a  or 1 to enable z
97d0: 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f  ero-damage.** mo
97e0: 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65  de.  If the inte
97f0: 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ger is -1, then 
9800: 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74 65  it is overwritte
9810: 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65  n with the curre
9820: 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67  nt.** zero-damag
9830: 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a  e mode setting..
9840: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9850: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
9860: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
9870: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
9880: 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  RITE] opcode is 
9890: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
98a0: 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a  e after opening.
98b0: 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e 73  ** a write trans
98c0: 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61  action to indica
98d0: 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20  te that, unless 
98e0: 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63  it is rolled bac
98f0: 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65  k for some.** re
9900: 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65  ason, the entire
9910: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9920: 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74  ill be overwritt
9930: 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65 6e  en by the curren
9940: 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  t .** transactio
9950: 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64 20  n. This is used 
9960: 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74  by VACUUM operat
9970: 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ions..**.** <li>
9980: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  [[SQLITE_FCNTL_V
9990: 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65  FSNAME]].** ^The
99a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56   [SQLITE_FCNTL_V
99b0: 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63  FSNAME] opcode c
99c0: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
99d0: 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f  tain the names o
99e0: 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d  f.** all [VFSes]
99f0: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61 63   in the VFS stac
9a00: 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72  k.  The names ar
9a10: 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69  e of all VFS shi
9a20: 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69  ms and the.** fi
9a30: 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c  nal bottom-level
9a40: 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65 6e   VFS are written
9a50: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
9a60: 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
9a70: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
9a80: 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74  ] and the result
9a90: 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68   is stored in th
9aa0: 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65  e char* variable
9ab0: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75  .** that the fou
9ac0: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66  rth parameter of
9ad0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9ae0: 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73  ontrol()] points
9af0: 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c   to..** The call
9b00: 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  er is responsibl
9b10: 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68  e for freeing th
9b20: 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f  e memory when do
9b30: 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20  ne.  As with.** 
9b40: 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  all file-control
9b50: 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20   actions, there 
9b60: 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20  is no guarantee 
9b70: 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61  that this will a
9b80: 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e  ctually.** do an
9b90: 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73  ything.  Callers
9ba0: 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69   should initiali
9bb0: 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61 72  ze the char* var
9bc0: 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a  iable to a NULL.
9bd0: 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61  ** pointer in ca
9be0: 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e  se this file-con
9bf0: 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c  trol is not impl
9c00: 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66  emented.  This f
9c10: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69  ile-control.** i
9c20: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64  s intended for d
9c30: 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e  iagnostic use on
9c40: 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ly..**.** <li>[[
9c50: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
9c60: 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76  GMA]].** ^Whenev
9c70: 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74  er a [PRAGMA] st
9c80: 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65  atement is parse
9c90: 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43  d, an [SQLITE_FC
9ca0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20  NTL_PRAGMA] .** 
9cb0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
9cc0: 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e  sent to the open
9cd0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
9ce0: 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e  object correspon
9cf0: 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64  ding.** to the d
9d00: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
9d10: 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d 61  which the pragma
9d20: 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72   statement refer
9d30: 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74  s. ^The argument
9d40: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49  .** to the [SQLI
9d50: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9d60: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
9d70: 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20   an array of.** 
9d80: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
9d90: 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20  ngs (char**) in 
9da0: 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64  which the second
9db0: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20   element of the 
9dc0: 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20  array.** is the 
9dd0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67  name of the prag
9de0: 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72 64  ma and the third
9df0: 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20   element is the 
9e00: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a  argument to the.
9e10: 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c  ** pragma or NUL
9e20: 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  L if the pragma 
9e30: 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e  has no argument.
9e40: 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66    ^The handler f
9e50: 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  or an.** [SQLITE
9e60: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
9e70: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20  ile control can 
9e80: 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20  optionally make 
9e90: 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e  the first elemen
9ea0: 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72  t.** of the char
9eb0: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e  ** argument poin
9ec0: 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62  t to a string ob
9ed0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c  tained from [sql
9ee0: 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a  ite3_mprintf()].
9ef0: 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76 61  ** or the equiva
9f00: 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74  lent and that st
9f10: 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65  ring will become
9f20: 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74   the result of t
9f30: 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20  he pragma or.** 
9f40: 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
9f50: 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61 20  e if the pragma 
9f60: 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a  fails. ^If the.*
9f70: 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  * [SQLITE_FCNTL_
9f80: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
9f90: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
9fa0: 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20  LITE_NOTFOUND], 
9fb0: 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20  then normal .** 
9fc0: 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73  [PRAGMA] process
9fd0: 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20  ing continues.  
9fe0: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
9ff0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
a000: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a010: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
a020: 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72 73  ], then the pars
a030: 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  er assumes that 
a040: 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68  the.** VFS has h
a050: 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d  andled the PRAGM
a060: 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65  A itself and the
a070: 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74 65   parser generate
a080: 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65  s a no-op.** pre
a090: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e  pared statement.
a0a0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
a0b0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a0c0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74  file control ret
a0d0: 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75  urns.** any resu
a0e0: 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68  lt code other th
a0f0: 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  an [SQLITE_OK] o
a100: 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  r [SQLITE_NOTFOU
a110: 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a  ND], that means.
a120: 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53 20  ** that the VFS 
a130: 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65  encountered an e
a140: 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c  rror while handl
a150: 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d  ing the [PRAGMA]
a160: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70   and the.** comp
a170: 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50  ilation of the P
a180: 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68  RAGMA fails with
a190: 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65   an error.  ^The
a1a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a1b0: 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63  RAGMA].** file c
a1c0: 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74  ontrol occurs at
a1d0: 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f   the beginning o
a1e0: 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65  f pragma stateme
a1f0: 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20  nt analysis and 
a200: 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65  so.** it is able
a210: 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69   to override bui
a220: 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73  lt-in [PRAGMA] s
a230: 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
a240: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
a250: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
a260: 5d 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c 65 2d  ].** ^This file-
a270: 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69  control may be i
a280: 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65  nvoked by SQLite
a290: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
a2a0: 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20   file handle.** 
a2b0: 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74  shortly after it
a2c0: 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72   is opened in or
a2d0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61  der to provide a
a2e0: 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68   custom VFS with
a2f0: 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68   access.** to th
a300: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75  e connections bu
a310: 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  sy-handler callb
a320: 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e  ack. The argumen
a330: 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f  t is of type (vo
a340: 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61  id **).** - an a
a350: 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69  rray of two (voi
a360: 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65  d *) values. The
a370: 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20   first (void *) 
a380: 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a  actually points.
a390: 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e  ** to a function
a3a0: 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a   of type (int (*
a3b0: 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f  )(void *)). In o
a3c0: 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74  rder to invoke t
a3d0: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  he connections.*
a3e0: 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20  * busy-handler, 
a3f0: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68  this function sh
a400: 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20  ould be invoked 
a410: 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20  with the second 
a420: 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74  (void *) in.** t
a430: 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65 20  he array as the 
a440: 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49  only argument. I
a450: 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e  f it returns non
a460: 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20  -zero, then the 
a470: 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  operation.** sho
a480: 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e 20  uld be retried. 
a490: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65  If it returns ze
a4a0: 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56  ro, the custom V
a4b0: 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f  FS should abando
a4c0: 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
a4d0: 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a   operation..**.*
a4e0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a4f0: 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d  CNTL_TEMPFILENAM
a500: 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74  E]].** ^Applicat
a510: 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74  ion can invoke t
a520: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a530: 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20   to have SQLite 
a540: 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65  generate a.** te
a550: 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65  mporary filename
a560: 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
a570: 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69  algorithm that i
a580: 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65  s followed to ge
a590: 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  nerate.** tempor
a5a0: 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f  ary filenames fo
a5b0: 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e  r TEMP tables an
a5c0: 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  d other internal
a5d0: 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61   uses.  The.** a
a5e0: 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
a5f0: 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68  e a char** which
a600: 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20   will be filled 
a610: 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d  with the filenam
a620: 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74  e.** written int
a630: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
a640: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
a650: 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20  malloc()].  The 
a660: 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a  caller should.**
a670: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
a680: 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20  _free()] on the 
a690: 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20  result to avoid 
a6a0: 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a  a memory leak..*
a6b0: 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  *.** </ul>.*/.#d
a6c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
a6d0: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
a6e0: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
a6f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
a700: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
a710: 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
a720: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
a730: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
a740: 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
a750: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
a760: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
a770: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
a780: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
a790: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
a7a0: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
a7b0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
a7c0: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
a7d0: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
a7e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
a7f0: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
a800: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
a810: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
a820: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
a830: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
a840: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
a850: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
a860: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
a870: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
a880: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
a890: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
a8a0: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
a8b0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
a8c0: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
a8d0: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
a8e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
a8f0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
a900: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
a910: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
a920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a930: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
a940: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
a950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a960: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
a970: 20 20 20 20 20 20 20 20 20 20 20 20 31 35 0a 23              15.#
a980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
a990: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
a9a0: 20 20 20 20 20 20 20 20 20 20 20 31 36 0a 0a 2f             16../
a9b0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
a9c0: 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  utex Handle.**.*
a9d0: 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75  * The mutex modu
a9e0: 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65  le within SQLite
a9f0: 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65   defines [sqlite
aa00: 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61  3_mutex] to be a
aa10: 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79  n.** abstract ty
aa20: 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f  pe for a mutex o
aa30: 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69  bject.  The SQLi
aa40: 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f  te core never lo
aa50: 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e  oks.** at the in
aa60: 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74  ternal represent
aa70: 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c  ation of an [sql
aa80: 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74  ite3_mutex].  It
aa90: 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77   only.** deals w
aaa0: 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ith pointers to 
aab0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
aac0: 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  ex] object..**.*
aad0: 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72  * Mutexes are cr
aae0: 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  eated using [sql
aaf0: 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63  ite3_mutex_alloc
ab00: 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
ab10: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
ab20: 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74  utex sqlite3_mut
ab30: 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ex;../*.** CAPI3
ab40: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
ab50: 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41  e Object.**.** A
ab60: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
ab70: 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62  e sqlite3_vfs ob
ab80: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
ab90: 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65   interface betwe
aba0: 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65  en.** the SQLite
abb0: 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e   core and the un
abc0: 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69  derlying operati
abd0: 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20  ng system.  The 
abe0: 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20  "vfs".** in the 
abf0: 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65  name of the obje
ac00: 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76  ct stands for "v
ac10: 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
ac20: 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65  em".  See.** the
ac30: 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75   [VFS | VFS docu
ac40: 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66  mentation] for f
ac50: 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69  urther informati
ac60: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  on..**.** The va
ac70: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
ac80: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
ac90: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
aca0: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
acb0: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
acc0: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
acd0: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
ace0: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
acf0: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
ad00: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
ad10: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
ad20: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
ad30: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
ad40: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
ad50: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
ad60: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
ad70: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
ad80: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
ad90: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
ada0: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
adb0: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
adc0: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
add0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
ade0: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
adf0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
ae00: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
ae10: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
ae20: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
ae30: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
ae40: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
ae50: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
ae60: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
ae70: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
ae80: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
ae90: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
aea0: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
aeb0: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
aec0: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
aed0: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
aee0: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
aef0: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
af00: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
af10: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
af20: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
af30: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
af40: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
af50: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
af60: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
af70: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
af80: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
af90: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
afa0: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
afb0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
afc0: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
afd0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
afe0: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
aff0: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
b000: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
b010: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
b020: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
b030: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
b040: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
b050: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
b060: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
b070: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
b080: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
b090: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
b0a0: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
b0b0: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
b0c0: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
b0d0: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
b0e0: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
b0f0: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
b100: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
b110: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
b120: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
b130: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
b140: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
b150: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
b160: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
b170: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
b180: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
b190: 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20  _vfs.xOpen]].** 
b1a0: 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65  ^SQLite guarante
b1b0: 65 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c  es that the zFil
b1c0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
b1d0: 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65  to xOpen.** is e
b1e0: 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ither a NULL poi
b1f0: 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f  nter or string o
b200: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
b210: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20  xFullPathname() 
b220: 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c  with an optional
b230: 20 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a   suffix added..*
b240: 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69  * ^If a suffix i
b250: 73 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a  s added to the z
b260: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
b270: 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63  er, it will.** c
b280: 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67  onsist of a sing
b290: 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  le "-" character
b2a0: 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20   followed by no 
b2b0: 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20  more than.** 11 
b2c0: 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64  alphanumeric and
b2d0: 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65  /or "-" characte
b2e0: 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66  rs..** ^SQLite f
b2f0: 75 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65  urther guarantee
b300: 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74  s that.** the st
b310: 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c  ring will be val
b320: 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64  id and unchanged
b330: 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20   until xClose() 
b340: 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65  is.** called. Be
b350: 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65  cause of the pre
b360: 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a  vious sentence,.
b370: 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
b380: 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79  file] can safely
b390: 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72   store a pointer
b3a0: 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e   to the.** filen
b3b0: 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20  ame if it needs 
b3c0: 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20  to remember the 
b3d0: 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d  filename for som
b3e0: 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20  e reason..** If 
b3f0: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
b400: 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e  rameter to xOpen
b410: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
b420: 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a  er then xOpen.**
b430: 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73   must invent its
b440: 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e   own temporary n
b450: 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65  ame for the file
b460: 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65  .  ^Whenever the
b470: 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70   .** xFilename p
b480: 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c  arameter is NULL
b490: 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65   it will also be
b4a0: 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
b4b0: 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61  he.** flags para
b4c0: 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75  meter will inclu
b4d0: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
b4e0: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a  DELETEONCLOSE]..
b4f0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
b500: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
b510: 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  n() includes all
b520: 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20   bits set in.** 
b530: 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
b540: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  nt to [sqlite3_o
b550: 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69  pen_v2()].  Or i
b560: 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  f [sqlite3_open(
b570: 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
b580: 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75  3_open16()] is u
b590: 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20  sed, then flags 
b5a0: 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73  includes at leas
b5b0: 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  t.** [SQLITE_OPE
b5c0: 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b  N_READWRITE] | [
b5d0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
b5e0: 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65  TE]. .** If xOpe
b5f0: 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65  n() opens a file
b600: 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20   read-only then 
b610: 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61  it sets *pOutFla
b620: 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65  gs to.** include
b630: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
b640: 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20  ADONLY].  Other 
b650: 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61  bits in *pOutFla
b660: 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a  gs may be set..*
b670: 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69  *.** ^(SQLite wi
b680: 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20  ll also add one 
b690: 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
b6a0: 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f   flags to the xO
b6b0: 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64  pen().** call, d
b6c0: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
b6d0: 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65  object being ope
b6e0: 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ned:.**.** <ul>.
b6f0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
b700: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a  _OPEN_MAIN_DB].*
b710: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
b720: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
b730: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
b740: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
b750: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
b760: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55  TE_OPEN_TEMP_JOU
b770: 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  RNAL].** <li>  [
b780: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e  SQLITE_OPEN_TRAN
b790: 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  SIENT_DB].** <li
b7a0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
b7b0: 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  SUBJOURNAL].** <
b7c0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
b7d0: 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c  N_MASTER_JOURNAL
b7e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
b7f0: 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20  TE_OPEN_WAL].** 
b800: 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
b810: 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65  e file I/O imple
b820: 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73  mentation can us
b830: 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70  e the object typ
b840: 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68  e flags to.** ch
b850: 61 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20  ange the way it 
b860: 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73  deals with files
b870: 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
b880: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a  an application.*
b890: 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  * that does not 
b8a0: 63 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68  care about crash
b8b0: 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c   recovery or rol
b8c0: 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65  lback might make
b8d0: 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20  .** the open of 
b8e0: 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61  a journal file a
b8f0: 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20   no-op.  Writes 
b900: 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20  to this journal 
b910: 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65  would.** also be
b920: 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79   no-ops, and any
b930: 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64   attempt to read
b940: 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75   the journal wou
b950: 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c  ld return.** SQL
b960: 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74  ITE_IOERR.  Or t
b970: 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
b980: 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a  n might recogniz
b990: 65 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73  e that a databas
b9a0: 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62  e.** file will b
b9b0: 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69  e doing page-ali
b9c0: 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64  gned sector read
b9d0: 73 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20  s and writes in 
b9e0: 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65  a random.** orde
b9f0: 72 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73  r and set up its
ba00: 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61   I/O subsystem a
ba10: 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a  ccordingly..**.*
ba20: 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61  * SQLite might a
ba30: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
ba40: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
ba50: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20  gs to the xOpen 
ba60: 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75  method:.**.** <u
ba70: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
ba80: 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e  TE_OPEN_DELETEON
ba90: 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  CLOSE].** <li> [
baa0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c  SQLITE_OPEN_EXCL
bab0: 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a  USIVE].** </ul>.
bac0: 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  **.** The [SQLIT
bad0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
bae0: 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73  LOSE] flag means
baf0: 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64   the file should
bb00: 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77   be.** deleted w
bb10: 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64  hen it is closed
bb20: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
bb30: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
bb40: 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73  SE].** will be s
bb50: 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61  et for TEMP data
bb60: 62 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20  bases and their 
bb70: 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69  journals, transi
bb80: 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73  ent.** databases
bb90: 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c  , and subjournal
bba0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53  s..**.** ^The [S
bbb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
bbc0: 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c  SIVE] flag is al
bbd0: 77 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e  ways used in con
bbe0: 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  junction.** with
bbf0: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
bc00: 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20  N_CREATE] flag, 
bc10: 77 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64  which are both d
bc20: 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f  irectly.** analo
bc30: 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58  gous to the O_EX
bc40: 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66  CL and O_CREAT f
bc50: 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49  lags of the POSI
bc60: 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e  X open().** API.
bc70: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45    The SQLITE_OPE
bc80: 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  N_EXCLUSIVE flag
bc90: 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69  , when paired wi
bca0: 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54  th the .** SQLIT
bcb0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69  E_OPEN_CREATE, i
bcc0: 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61  s used to indica
bcd0: 74 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f  te that file sho
bce0: 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65  uld always.** be
bcf0: 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68   created, and th
bd00: 61 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f  at it is an erro
bd10: 72 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20  r if it already 
bd20: 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73  exists..** It is
bd30: 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64   <i>not</i> used
bd40: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65   to indicate the
bd50: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20   file should be 
bd60: 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65  opened .** for e
bd70: 78 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e  xclusive access.
bd80: 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74  .**.** ^At least
bd90: 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20   szOsFile bytes 
bda0: 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c  of memory are al
bdb0: 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74  located by SQLit
bdc0: 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65  e.** to hold the
bdd0: 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d    [sqlite3_file]
bde0: 20 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65   structure passe
bdf0: 64 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a  d as the third.*
be00: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  * argument to xO
be10: 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20  pen.  The xOpen 
be20: 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20  method does not 
be30: 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63  have to.** alloc
be40: 61 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72  ate the structur
be50: 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73  e; it should jus
be60: 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e  t fill it in.  N
be70: 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ote that.** the 
be80: 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73  xOpen method mus
be90: 74 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  t set the sqlite
bea0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
beb0: 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76  to either.** a v
bec0: 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f  alid [sqlite3_io
bed0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
bee0: 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f   or to NULL.  xO
bef0: 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74  pen must do.** t
bf00: 68 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20  his even if the 
bf10: 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c  open fails.  SQL
bf20: 69 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74  ite expects that
bf30: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
bf40: 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c  e.pMethods.** el
bf50: 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61  ement will be va
bf60: 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20  lid after xOpen 
bf70: 72 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65  returns regardle
bf80: 73 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73  ss of the succes
bf90: 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20  s.** or failure 
bfa0: 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c  of the xOpen cal
bfb0: 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  l..**.** [[sqlit
bfc0: 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d  e3_vfs.xAccess]]
bfd0: 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61  .** ^The flags a
bfe0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65  rgument to xAcce
bff0: 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c  ss() may be [SQL
c000: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
c010: 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f  S].** to test fo
c020: 72 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20  r the existence 
c030: 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53  of a file, or [S
c040: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
c050: 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65  DWRITE] to.** te
c060: 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c  st whether a fil
c070: 65 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e  e is readable an
c080: 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b  d writable, or [
c090: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
c0a0: 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77  AD].** to test w
c0b0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
c0c0: 20 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62   at least readab
c0d0: 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63  le.   The file c
c0e0: 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63  an be a.** direc
c0f0: 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  tory..**.** ^SQL
c100: 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ite will always 
c110: 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73  allocate at leas
c120: 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62  t mxPathname+1 b
c130: 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ytes for the.** 
c140: 6f 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46  output buffer xF
c150: 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68  ullPathname.  Th
c160: 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20  e exact size of 
c170: 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65  the output buffe
c180: 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73  r.** is also pas
c190: 73 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74  sed as a paramet
c1a0: 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68  er to both  meth
c1b0: 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70  ods. If the outp
c1c0: 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20  ut buffer.** is 
c1d0: 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68  not large enough
c1e0: 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  , [SQLITE_CANTOP
c1f0: 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65  EN] should be re
c200: 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68  turned. Since th
c210: 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64  is is.** handled
c220: 20 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f   as a fatal erro
c230: 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73  r by SQLite, vfs
c240: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
c250: 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72   should endeavor
c260: 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74  .** to prevent t
c270: 68 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d  his by setting m
c280: 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73  xPathname to a s
c290: 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67  ufficiently larg
c2a0: 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54  e value..**.** T
c2b0: 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
c2c0: 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72  , xSleep(), xCur
c2d0: 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20  rentTime(), and 
c2e0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c2f0: 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  4().** interface
c300: 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74  s are not strict
c310: 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65  ly a part of the
c320: 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74   filesystem, but
c330: 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63   they are.** inc
c340: 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53  luded in the VFS
c350: 20 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63   structure for c
c360: 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20  ompleteness..** 
c370: 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28  The xRandomness(
c380: 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d  ) function attem
c390: 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42  pts to return nB
c3a0: 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66  ytes bytes.** of
c3b0: 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61   good-quality ra
c3c0: 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f  ndomness into zO
c3d0: 75 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20  ut.  The return 
c3e0: 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20  value is.** the 
c3f0: 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66  actual number of
c400: 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
c410: 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a  ness obtained..*
c420: 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d  * The xSleep() m
c430: 65 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65  ethod causes the
c440: 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20   calling thread 
c450: 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a  to sleep for at.
c460: 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d  ** least the num
c470: 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f  ber of microseco
c480: 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65  nds given.  ^The
c490: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a   xCurrentTime().
c4a0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
c4b0: 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e  s a Julian Day N
c4c0: 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75  umber for the cu
c4d0: 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74  rrent date and t
c4e0: 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61  ime as.** a floa
c4f0: 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
c500: 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65  ..** ^The xCurre
c510: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
c520: 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73  thod returns, as
c530: 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65   an integer, the
c540: 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e   Julian.** Day N
c550: 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64  umber multiplied
c560: 20 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68   by 86400000 (th
c570: 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
c580: 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20  iseconds in .** 
c590: 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20  a 24-hour day). 
c5a0: 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c   .** ^SQLite wil
c5b0: 6c 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65  l use the xCurre
c5c0: 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65  ntTimeInt64() me
c5d0: 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20  thod to get the 
c5e0: 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20  current.** date 
c5f0: 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74  and time if that
c600: 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c   method is avail
c610: 61 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f  able (if iVersio
c620: 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72  n is 2 or .** gr
c630: 65 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75  eater and the fu
c640: 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
c650: 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20  s not NULL) and 
c660: 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a  will fall back.*
c670: 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d  * to xCurrentTim
c680: 65 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54  e() if xCurrentT
c690: 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e  imeInt64() is un
c6a0: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  available..**.**
c6b0: 20 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d   ^The xSetSystem
c6c0: 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74  Call(), xGetSyst
c6d0: 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e  emCall(), and xN
c6e0: 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20  estSystemCall() 
c6f0: 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72  interfaces.** ar
c700: 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68  e not used by th
c710: 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20  e SQLite core.  
c720: 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69  These optional i
c730: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72  nterfaces are pr
c740: 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d  ovided.** by som
c750: 65 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c  e VFSes to facil
c760: 69 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66  itate testing of
c770: 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42   the VFS code. B
c780: 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a  y overriding .**
c790: 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69   system calls wi
c7a0: 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64  th functions und
c7b0: 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20  er its control, 
c7c0: 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63  a test program c
c7d0: 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66  an.** simulate f
c7e0: 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20  aults and error 
c7f0: 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20  conditions that 
c800: 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20  would otherwise 
c810: 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20  be difficult.** 
c820: 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f  or impossible to
c830: 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65   induce.  The se
c840: 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c  t of system call
c850: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76  s that can be ov
c860: 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69  erridden.** vari
c870: 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20  es from one VFS 
c880: 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20  to another, and 
c890: 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e  from one version
c8a0: 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53   of the same VFS
c8b0: 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e   to the.** next.
c8c0: 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74    Applications t
c8d0: 68 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e  hat use these in
c8e0: 74 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65  terfaces must be
c8f0: 20 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e   prepared for an
c900: 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74  y.** or all of t
c910: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
c920: 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f  to be NULL or fo
c930: 72 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72  r their behavior
c940: 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72   to change.** fr
c950: 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74  om one release t
c960: 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70  o the next.  App
c970: 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e  lications must n
c980: 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63  ot attempt to ac
c990: 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74  cess.** any of t
c9a0: 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20  hese methods if 
c9b0: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20  the iVersion of 
c9c0: 74 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20  the VFS is less 
c9d0: 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64  than 3..*/.typed
c9e0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
c9f0: 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66  3_vfs sqlite3_vf
ca00: 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  s;.typedef void 
ca10: 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  (*sqlite3_syscal
ca20: 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74  l_ptr)(void);.st
ca30: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
ca40: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
ca50: 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  n;            /*
ca60: 20 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69   Structure versi
ca70: 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65  on number (curre
ca80: 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74  ntly 3) */.  int
ca90: 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20   szOsFile;      
caa0: 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66        /* Size of
cab0: 20 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69   subclassed sqli
cac0: 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e  te3_file */.  in
cad0: 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20  t mxPathname;   
cae0: 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
caf0: 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20  m file pathname 
cb00: 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69  length */.  sqli
cb10: 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20  te3_vfs *pNext; 
cb20: 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67       /* Next reg
cb30: 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20  istered VFS */. 
cb40: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
cb50: 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  me;       /* Nam
cb60: 65 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61  e of this virtua
cb70: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f  l file system */
cb80: 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
cb90: 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50  a;          /* P
cba0: 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63  ointer to applic
cbb0: 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64  ation-specific d
cbc0: 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ata */.  int (*x
cbd0: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
cbe0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
cbf0: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66  zName, sqlite3_f
cc00: 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20  ile*,.          
cc10: 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20       int flags, 
cc20: 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b  int *pOutFlags);
cc30: 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65  .  int (*xDelete
cc40: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
cc50: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
cc60: 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b  e, int syncDir);
cc70: 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73  .  int (*xAccess
cc80: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
cc90: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
cca0: 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e  e, int flags, in
ccb0: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
ccc0: 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61  nt (*xFullPathna
ccd0: 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  me)(sqlite3_vfs*
cce0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
ccf0: 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63  ame, int nOut, c
cd00: 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f  har *zOut);.  vo
cd10: 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73  id *(*xDlOpen)(s
cd20: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
cd30: 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
cd40: 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  me);.  void (*xD
cd50: 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  lError)(sqlite3_
cd60: 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
cd70: 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b   char *zErrMsg);
cd80: 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53  .  void (*(*xDlS
cd90: 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ym)(sqlite3_vfs*
cda0: 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68  ,void*, const ch
cdb0: 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f  ar *zSymbol))(vo
cdc0: 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44  id);.  void (*xD
cdd0: 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  lClose)(sqlite3_
cde0: 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20  vfs*, void*);.  
cdf0: 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73  int (*xRandomnes
ce00: 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  s)(sqlite3_vfs*,
ce10: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
ce20: 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28   *zOut);.  int (
ce30: 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33  *xSleep)(sqlite3
ce40: 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f  _vfs*, int micro
ce50: 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20  seconds);.  int 
ce60: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28  (*xCurrentTime)(
ce70: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f  sqlite3_vfs*, do
ce80: 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  uble*);.  int (*
ce90: 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73  xGetLastError)(s
cea0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
ceb0: 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a  , char *);.  /*.
cec0: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
ced0: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
cee0: 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73  rsion 1 of the s
cef0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
cf00: 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e  .  ** definition
cf10: 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f  .  Those that fo
cf20: 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69  llow are added i
cf30: 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c  n version 2 or l
cf40: 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20  ater.  */.  int 
cf50: 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  (*xCurrentTimeIn
cf60: 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73  t64)(sqlite3_vfs
cf70: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
cf80: 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
cf90: 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
cfa0: 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20  are in versions 
cfb0: 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73  1 and 2 of the s
cfc0: 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74  qlite_vfs object
cfd0: 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c  ..  ** Those bel
cfe0: 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69  ow are for versi
cff0: 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72  on 3 and greater
d000: 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ..  */.  int (*x
d010: 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  SetSystemCall)(s
d020: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
d030: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
d040: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
d050: 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f  ptr);.  sqlite3_
d060: 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47  syscall_ptr (*xG
d070: 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
d080: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
d090: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a  t char *zName);.
d0a0: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a    const char *(*
d0b0: 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29  xNextSystemCall)
d0c0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d0d0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d0e0: 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
d0f0: 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
d100: 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
d110: 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68   through 3 of th
d120: 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a  e sqlite_vfs obj
d130: 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69  ect..  ** New fi
d140: 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65  elds may be appe
d150: 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76  nded in figure v
d160: 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56  ersions.  The iV
d170: 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75  ersion.  ** valu
d180: 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74  e will increment
d190: 20 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68   whenever this h
d1a0: 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b  appens. .  */.};
d1b0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
d1c0: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
d1d0: 78 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68  xAccess VFS meth
d1e0: 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69  od.**.** These i
d1f0: 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73  nteger constants
d200: 20 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20   can be used as 
d210: 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
d220: 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41  ter to.** the xA
d230: 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  ccess method of 
d240: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  an [sqlite3_vfs]
d250: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64   object.  They d
d260: 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74  etermine.** what
d270: 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73   kind of permiss
d280: 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73  ions the xAccess
d290: 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69   method is looki
d2a0: 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20  ng for..** With 
d2b0: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58  SQLITE_ACCESS_EX
d2c0: 49 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73  ISTS, the xAcces
d2d0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70  s method.** simp
d2e0: 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ly checks whethe
d2f0: 72 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74  r the file exist
d300: 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  s..** With SQLIT
d310: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
d320: 54 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TE, the xAccess 
d330: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
d340: 20 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d   whether the nam
d350: 65 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20  ed directory is 
d360: 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e  both readable an
d370: 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69  d writable.** (i
d380: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
d390: 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61  f files can be a
d3a0: 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61  dded, removed, a
d3b0: 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69  nd renamed withi
d3c0: 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f  n.** the directo
d3d0: 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ry)..** The SQLI
d3e0: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52  TE_ACCESS_READWR
d3f0: 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20  ITE constant is 
d400: 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f  currently used o
d410: 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74  nly by the.** [t
d420: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
d430: 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f  ory pragma], tho
d440: 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63  ugh this could c
d450: 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72  hange in a futur
d460: 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20  e.** release of 
d470: 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20  SQLite..** With 
d480: 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
d490: 41 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  AD, the xAccess 
d4a0: 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73  method.** checks
d4b0: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
d4c0: 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20  e is readable.  
d4d0: 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  The SQLITE_ACCES
d4e0: 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20  S_READ constant 
d4f0: 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  is.** currently 
d500: 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69  unused, though i
d510: 74 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20  t might be used 
d520: 69 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65  in a future rele
d530: 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
d540: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
d550: 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54  ITE_ACCESS_EXIST
d560: 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53  S    0.#define S
d570: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d580: 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73  DWRITE 1   /* Us
d590: 65 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d  ed by PRAGMA tem
d5a0: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
d5b0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
d5c0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
d5d0: 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73       2   /* Unus
d5e0: 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
d5f0: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
d600: 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46   the xShmLock VF
d610: 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54  S method.**.** T
d620: 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  hese integer con
d630: 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68  stants define th
d640: 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e  e various lockin
d650: 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20  g operations.** 
d660: 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78  allowed by the x
d670: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f  ShmLock method o
d680: 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  f [sqlite3_io_me
d690: 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20  thods].  The.** 
d6a0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68  following are th
d6b0: 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d  e only legal com
d6c0: 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61  binations of fla
d6d0: 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68  gs to the.** xSh
d6e0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a  mLock method:.**
d6f0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
d700: 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43    SQLITE_SHM_LOC
d710: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53  K | SQLITE_SHM_S
d720: 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53  HARED.** <li>  S
d730: 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c  QLITE_SHM_LOCK |
d740: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
d750: 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53  USIVE.** <li>  S
d760: 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
d770: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
d780: 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
d790: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
d7a0: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  | SQLITE_SHM_EXC
d7b0: 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a  LUSIVE.** </ul>.
d7c0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63  **.** When unloc
d7d0: 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53  king, the same S
d7e0: 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49  HARED or EXCLUSI
d7f0: 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20  VE flag must be 
d800: 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77  supplied as.** w
d810: 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20  as given no the 
d820: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f  corresponding lo
d830: 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ck.  .**.** The 
d840: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
d850: 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62  can transition b
d860: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
d870: 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a  and SHARED or.**
d880: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
d890: 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  d and EXCLUSIVE.
d8a0: 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e    It cannot tran
d8b0: 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53  sition between S
d8c0: 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43  HARED.** and EXC
d8d0: 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69  LUSIVE..*/.#defi
d8e0: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  ne SQLITE_SHM_UN
d8f0: 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65  LOCK       1.#de
d900: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
d910: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23  LOCK         2.#
d920: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
d930: 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34  M_SHARED       4
d940: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d950: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20  SHM_EXCLUSIVE   
d960: 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   8../*.** CAPI3R
d970: 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d  EF: Maximum xShm
d980: 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a  Lock index.**.**
d990: 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
d9a0: 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33  thod on [sqlite3
d9b0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79  _io_methods] may
d9c0: 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62   use values.** b
d9d0: 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69  etween 0 and thi
d9e0: 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73  s upper bound as
d9f0: 20 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72   its "offset" ar
da00: 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53  gument..** The S
da10: 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20  QLite core will 
da20: 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f  never attempt to
da30: 20 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65   acquire or rele
da40: 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75  ase a.** lock ou
da50: 74 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61  tside of this ra
da60: 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nge.*/.#define S
da70: 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20  QLITE_SHM_NLOCK 
da80: 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a         8.../*.**
da90: 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69   CAPI3REF: Initi
daa0: 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65  alize The SQLite
dab0: 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e   Library.**.** ^
dac0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
dad0: 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
dae0: 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65   initializes the
daf0: 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61  .** SQLite libra
db00: 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ry.  ^The sqlite
db10: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75  3_shutdown() rou
db20: 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61  tine.** dealloca
db30: 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65  tes any resource
db40: 73 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f  s that were allo
db50: 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
db60: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a  _initialize()..*
db70: 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
db80: 20 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f   are designed to
db90: 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20   aid in process 
dba0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
dbb0: 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f  nd.** shutdown o
dbc0: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
dbd0: 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e  ms.  Workstation
dbe0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73   applications us
dbf0: 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f  ing.** SQLite no
dc00: 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65  rmally do not ne
dc10: 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74  ed to invoke eit
dc20: 68 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75  her of these rou
dc30: 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63  tines..**.** A c
dc40: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  all to sqlite3_i
dc50: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61  nitialize() is a
dc60: 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
dc70: 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74  ll if it is.** t
dc80: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
dc90: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
dca0: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75  () is invoked du
dcb0: 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d  ring the lifetim
dcc0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63  e of.** the proc
dcd0: 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73  ess, or if it is
dce0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
dcf0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
dd00: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
dd10: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63  ** following a c
dd20: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
dd30: 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e  hutdown().  ^(On
dd40: 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20  ly an effective 
dd50: 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  call.** of sqlit
dd60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
dd70: 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c  does any initial
dd80: 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74  ization.  All ot
dd90: 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65  her calls.** are
dda0: 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
ddb0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c  .)^.**.** A call
ddc0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
ddd0: 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66  down() is an "ef
dde0: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
ddf0: 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74   it is the first
de00: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  .** call to sqli
de10: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73  te3_shutdown() s
de20: 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71  ince the last sq
de30: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
de40: 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61  ().  ^(Only.** a
de50: 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
de60: 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74   to sqlite3_shut
de70: 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20  down() does any 
de80: 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  deinitialization
de90: 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76  ..** All other v
dea0: 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71  alid calls to sq
deb0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
dec0: 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f   are harmless no
ded0: 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  -ops.)^.**.** Th
dee0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
def0: 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65  lize() interface
df00: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20   is threadsafe, 
df10: 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74  but sqlite3_shut
df20: 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  down().** is not
df30: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73  .  The sqlite3_s
df40: 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66  hutdown() interf
df50: 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65  ace must only be
df60: 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a   called from a.*
df70: 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  * single thread.
df80: 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61    All open [data
df90: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
dfa0: 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  ] must be closed
dfb0: 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65   and all.** othe
dfc0: 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63  r SQLite resourc
dfd0: 65 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c  es must be deall
dfe0: 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20  ocated prior to 
dff0: 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69  invoking.** sqli
e000: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a  te3_shutdown()..
e010: 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65  **.** Among othe
e020: 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74  r things, ^sqlit
e030: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e040: 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  will invoke.** s
e050: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
e060: 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73  .  Similarly, ^s
e070: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e080: 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ).** will invoke
e090: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
e0a0: 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )..**.** ^The sq
e0b0: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
e0c0: 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
e0d0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  ns [SQLITE_OK] o
e0e0: 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49  n success..** ^I
e0f0: 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  f for some reaso
e100: 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  n, sqlite3_initi
e110: 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c  alize() is unabl
e120: 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a  e to initialize.
e130: 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28  ** the library (
e140: 70 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e  perhaps it is un
e150: 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  able to allocate
e160: 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72   a needed resour
e170: 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20  ce such.** as a 
e180: 6d 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e  mutex) it return
e190: 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65  s an [error code
e1a0: 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  ] other than [SQ
e1b0: 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
e1c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
e1d0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
e1e0: 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65  e is called inte
e1f0: 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f  rnally by many o
e200: 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ther.** SQLite i
e210: 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61  nterfaces so tha
e220: 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  t an application
e230: 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f   usually does no
e240: 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76  t need to.** inv
e250: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
e260: 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
e270: 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c  y.  For example,
e280: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
e290: 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74  ].** calls sqlit
e2a0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e2b0: 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  so the SQLite li
e2c0: 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75  brary will be au
e2d0: 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69  tomatically.** i
e2e0: 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20  nitialized when 
e2f0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
e300: 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74   is called if it
e310: 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74   has not be init
e320: 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61  ialized.** alrea
e330: 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69  dy.  ^However, i
e340: 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
e350: 69 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53  iled with the [S
e360: 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49  QLITE_OMIT_AUTOI
e370: 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  NIT].** compile-
e380: 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65  time option, the
e390: 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20  n the automatic 
e3a0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
e3b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a  _initialize().**
e3c0: 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64   are omitted and
e3d0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
e3e0: 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74   must call sqlit
e3f0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
e400: 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f  directly.** prio
e410: 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
e420: 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
e430: 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69  rface.  For maxi
e440: 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c  mum portability,
e450: 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d  .** it is recomm
e460: 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69  ended that appli
e470: 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69  cations always i
e480: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
e490: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69  itialize().** di
e4a0: 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20  rectly prior to 
e4b0: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
e4c0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
e4d0: 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73  .  Future releas
e4e0: 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  es.** of SQLite 
e4f0: 6d 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73  may require this
e500: 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
e510: 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  s, the behavior 
e520: 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65  exhibited.** whe
e530: 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
e540: 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
e550: 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
e560: 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68   might become th
e570: 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68  e.** default beh
e580: 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75  avior in some fu
e590: 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20  ture release of 
e5a0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
e5b0: 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  e sqlite3_os_ini
e5c0: 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73  t() routine does
e5d0: 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
e5e0: 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e  m specific.** in
e5f0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20  itialization of 
e600: 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61  the SQLite libra
e610: 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ry.  The sqlite3
e620: 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75  _os_end().** rou
e630: 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20  tine undoes the 
e640: 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65  effect of sqlite
e650: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79  3_os_init().  Ty
e660: 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70  pical tasks.** p
e670: 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73  erformed by thes
e680: 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75  e routines inclu
e690: 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72  de allocation or
e6a0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
e6b0: 20 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75   of static resou
e6c0: 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61  rces, initializa
e6d0: 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76  tion of global v
e6e0: 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74  ariables,.** set
e6f0: 74 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c  ting up a defaul
e700: 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
e710: 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69  module, or setti
e720: 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75  ng up.** a defau
e730: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
e740: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
e750: 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a  config()]..**.**
e760: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
e770: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e   should never in
e780: 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69  voke either sqli
e790: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a  te3_os_init().**
e7a0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65   or sqlite3_os_e
e7b0: 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  nd() directly.  
e7c0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
e7d0: 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f  should only invo
e7e0: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e  ke.** sqlite3_in
e7f0: 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73  itialize() and s
e800: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
e810: 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  ).  The sqlite3_
e820: 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74  os_init().** int
e830: 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64  erface is called
e840: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62   automatically b
e850: 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
e860: 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71  lize() and.** sq
e870: 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69  lite3_os_end() i
e880: 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69  s called by sqli
e890: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
e8a0: 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20   Appropriate.** 
e8b0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
e8c0: 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  for sqlite3_os_i
e8d0: 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
e8e0: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72  3_os_end().** ar
e8f0: 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  e built into SQL
e900: 69 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63  ite when it is c
e910: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78  ompiled for Unix
e920: 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53  , Windows, or OS
e930: 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73  /2..** When [cus
e940: 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69  tom builds | bui
e950: 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61  lt for other pla
e960: 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e  tforms].** (usin
e970: 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53  g the [SQLITE_OS
e980: 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c  _OTHER=1] compil
e990: 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e  e-time.** option
e9a0: 29 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ) the applicatio
e9b0: 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20  n must supply a 
e9c0: 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65  suitable impleme
e9d0: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73  ntation for.** s
e9e0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
e9f0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
ea00: 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69  end().  An appli
ea10: 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a  cation-supplied.
ea20: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
ea30: 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  n of sqlite3_os_
ea40: 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65  init() or sqlite
ea50: 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75  3_os_end().** mu
ea60: 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  st return [SQLIT
ea70: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
ea80: 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20   and some other 
ea90: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f  [error code] upo
eaa0: 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f  n.** failure..*/
eab0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
eac0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ead0: 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  ze(void);.SQLITE
eae0: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
eaf0: 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b  _shutdown(void);
eb00: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
eb10: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
eb20: 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50  void);.SQLITE_AP
eb30: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  I int sqlite3_os
eb40: 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a  _end(void);../*.
eb50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
eb60: 66 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c  figuring The SQL
eb70: 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a  ite Library.**.*
eb80: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
eb90: 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
eba0: 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   is used to make
ebb0: 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72   global configur
ebc0: 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73  ation.** changes
ebd0: 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   to SQLite in or
ebe0: 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69  der to tune SQLi
ebf0: 74 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66  te to the specif
ec00: 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74  ic needs of.** t
ec10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20  he application. 
ec20: 20 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e   The default con
ec30: 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65  figuration is re
ec40: 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f  commended for mo
ec50: 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
ec60: 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72  ns and so this r
ec70: 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c  outine is usuall
ec80: 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e  y not necessary.
ec90: 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69    It is.** provi
eca0: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72  ded to support r
ecb0: 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  are applications
ecc0: 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65   with unusual ne
ecd0: 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  eds..**.** The s
ece0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ecf0: 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
ed00: 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
ed10: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  e application.**
ed20: 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61   must insure tha
ed30: 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  t no other SQLit
ed40: 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  e interfaces are
ed50: 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65   invoked by othe
ed60: 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69  r.** threads whi
ed70: 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  le sqlite3_confi
ed80: 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20  g() is running. 
ed90: 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71   Furthermore, sq
eda0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a  lite3_config().*
edb0: 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e  * may only be in
edc0: 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c  voked prior to l
edd0: 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a  ibrary initializ
ede0: 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
edf0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ee00: 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73  ze()] or after s
ee10: 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69  hutdown by [sqli
ee20: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e  te3_shutdown()].
ee30: 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
ee40: 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c  config() is call
ee50: 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
ee60: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
ee70: 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73  and before.** [s
ee80: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ee90: 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20  )] then it will 
eea0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49  return SQLITE_MI
eeb0: 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68  SUSE..** Note, h
eec0: 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71  owever, that ^sq
eed0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63  lite3_config() c
eee0: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20  an be called as 
eef0: 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69  part of the.** i
ef00: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
ef10: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
ef20: 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33  defined [sqlite3
ef30: 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a  _os_init()]..**.
ef40: 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
ef50: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
ef60: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20  _config() is an 
ef70: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66  integer.** [conf
ef80: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ef90: 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  ] that determine
efa0: 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72  s.** what proper
efb0: 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20  ty of SQLite is 
efc0: 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64  to be configured
efd0: 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  .  Subsequent ar
efe0: 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20  guments.** vary 
eff0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
f000: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
f010: 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  option].** in th
f020: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
f030: 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20  ..**.** ^When a 
f040: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f050: 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c  tion is set, sql
f060: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65  ite3_config() re
f070: 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
f080: 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70  ]..** ^If the op
f090: 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20  tion is unknown 
f0a0: 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  or SQLite is una
f0b0: 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f  ble to set the o
f0c0: 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68  ption.** then th
f0d0: 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
f0e0: 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  ns a non-zero [e
f0f0: 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53  rror code]..*/.S
f100: 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
f110: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
f120: 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
f130: 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
f140: 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
f150: 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  ections.**.** Th
f160: 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
f170: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
f180: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
f190: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
f1a0: 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
f1b0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f1c0: 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
f1d0: 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
f1e0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
f1f0: 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
f200: 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
f210: 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
f220: 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
f230: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
f240: 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
f250: 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
f260: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
f270: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
f280: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
f290: 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
f2a0: 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
f2b0: 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
f2c0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
f2d0: 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
f2e0: 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
f2f0: 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
f300: 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
f310: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
f320: 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
f330: 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
f340: 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
f350: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
f360: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
f370: 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
f380: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
f390: 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
f3a0: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
f3b0: 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
f3c0: 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
f3d0: 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
f3e0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
f3f0: 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
f400: 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
f410: 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
f420: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
f430: 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
f440: 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
f450: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
f460: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
f470: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
f480: 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
f490: 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
f4a0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f4b0: 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
f4c0: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
f4d0: 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
f4e0: 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
f4f0: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
f500: 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
f510: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
f520: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
f530: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
f540: 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
f550: 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
f560: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f570: 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
f580: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
f590: 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
f5a0: 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
f5b0: 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
f5c0: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
f5d0: 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
f5e0: 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
f5f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
f600: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
f610: 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
f620: 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
f630: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
f640: 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
f650: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
f660: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
f670: 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
f680: 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
f690: 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
f6a0: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
f6b0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
f6c0: 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
f6d0: 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
f6e0: 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
f6f0: 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
f700: 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
f710: 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
f720: 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
f730: 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
f740: 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
f750: 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
f760: 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
f770: 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
f780: 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
f790: 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
f7a0: 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
f7b0: 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
f7c0: 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
f7d0: 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
f7e0: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
f7f0: 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
f800: 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
f810: 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
f820: 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
f830: 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
f840: 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
f850: 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
f860: 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
f870: 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
f880: 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
f890: 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
f8a0: 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
f8b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
f8c0: 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
f8d0: 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
f8e0: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
f8f0: 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
f900: 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
f910: 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
f920: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
f930: 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
f940: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
f950: 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
f960: 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
f970: 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
f980: 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
f990: 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
f9a0: 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
f9b0: 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
f9c0: 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
f9d0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
f9e0: 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
f9f0: 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
fa00: 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
fa10: 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
fa20: 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
fa30: 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
fa40: 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
fa50: 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
fa60: 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
fa70: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
fa80: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
fa90: 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
faa0: 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
fab0: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
fac0: 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
fad0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
fae0: 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
faf0: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
fb00: 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
fb10: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
fb20: 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
fb30: 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
fb40: 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
fb50: 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
fb60: 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
fb70: 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
fb80: 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
fb90: 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
fba0: 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
fbb0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
fbc0: 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
fbd0: 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
fbe0: 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
fbf0: 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
fc00: 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
fc10: 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
fc20: 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
fc30: 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
fc40: 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
fc50: 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
fc60: 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
fc70: 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
fc80: 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
fc90: 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
fca0: 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78  ocator.  (For ex
fcb0: 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
fcc0: 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
fcd0: 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
fce0: 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
fcf0: 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
fd00: 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
fd10: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
fd20: 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
fd30: 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
fd40: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
fd50: 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
fd60: 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
fd70: 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
fd80: 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
fd90: 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
fda0: 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
fdb0: 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
fdc0: 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
fdd0: 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
fde0: 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
fdf0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
fe00: 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
fe10: 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
fe20: 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
fe30: 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
fe40: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
fe50: 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
fe60: 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
fe70: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
fe80: 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
fe90: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
fea0: 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
feb0: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
fec0: 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
fed0: 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
fee0: 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
fef0: 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
ff00: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
ff10: 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
ff20: 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
ff30: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
ff40: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
ff50: 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
ff60: 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
ff70: 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
ff80: 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
ff90: 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
ffa0: 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
ffb0: 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
ffc0: 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
ffd0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
ffe0: 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
fff0: 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
10000 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
10010 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
10020 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
10030 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
10040 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
10050 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
10060 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
10070 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
10080 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
10090 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
100a0 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
100b0 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
100c0 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
100d0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
100e0 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
100f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
10100 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
10110 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
10120 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
10130 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
10140 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10150 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
10160 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
10170 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
10180 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
10190 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
101a0 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
101b0 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
101c0 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
101d0 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
101e0 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
101f0 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
10200 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
10210 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
10220 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
10230 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
10240 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
10250 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
10260 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
10270 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
10280 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
10290 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
102a0 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
102b0 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
102c0 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
102d0 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
102e0 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
102f0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
10300 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
10310 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
10320 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
10330 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
10340 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
10350 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
10360 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
10370 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
10380 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  : {configuration
10390 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54   option}.**.** T
103a0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
103b0 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65  re the available
103c0 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75   integer configu
103d0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74  ration options t
103e0 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61  hat.** can be pa
103f0 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73  ssed as the firs
10400 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
10410 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
10420 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
10430 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
10440 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
10450 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
10460 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
10470 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
10480 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
10490 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
104a0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
104b0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
104c0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
104d0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
104e0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
104f0 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b  config()] to mak
10500 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74  e sure that.** t
10510 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20  he call worked. 
10520 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   The [sqlite3_co
10530 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
10540 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
10550 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
10560 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
10570 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
10580 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
10590 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
105a0 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
105b0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
105c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
105d0 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  LETHREAD]] <dt>S
105e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
105f0 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  GLETHREAD</dt>.*
10600 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
10610 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
10620 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
10630 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
10640 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
10650 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c  g mode] to Singl
10660 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  e-thread.  In ot
10670 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
10680 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  sables.** all mu
10690 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20  texing and puts 
106a0 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f  SQLite into a mo
106b0 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20  de where it can 
106c0 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20  only be used.** 
106d0 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65  by a single thre
106e0 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  ad.   ^If SQLite
106f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
10700 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
10710 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
10720 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
10730 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
10740 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
10750 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
10760 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20  e to change the 
10770 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
10780 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c   from its defaul
10790 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69  t.** value of Si
107a0 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20  ngle-thread and 
107b0 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  so [sqlite3_conf
107c0 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ig()] will retur
107d0 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52  n .** [SQLITE_ER
107e0 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
107f0 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
10800 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
10810 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  AD.** configurat
10820 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
10830 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
10840 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
10850 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AD]] <dt>SQLITE_
10860 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
10870 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
10880 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
10890 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
108a0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
108b0 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
108c0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
108d0 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64   to Multi-thread
108e0 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
108f0 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
10900 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64  * mutexing on [d
10910 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10920 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
10930 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
10940 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ects..** The app
10950 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70  lication is resp
10960 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69  onsible for seri
10970 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74  alizing access t
10980 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  o.** [database c
10990 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
109a0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
109b0 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65  ents].  But othe
109c0 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65  r mutexes.** are
109d0 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74   enabled so that
109e0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
109f0 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61  safe to use in a
10a00 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a   multi-threaded.
10a10 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61  ** environment a
10a20 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
10a30 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74   threads attempt
10a40 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65   to use the same
10a50 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
10a60 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65  nnection] at the
10a70 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66   same time.  ^If
10a80 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
10a90 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
10aa0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
10ab0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
10ac0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
10ad0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
10ae0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
10af0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
10b00 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64  the Multi-thread
10b10 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
10b20 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
10b30 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
10b40 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
10b50 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
10b60 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
10b70 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
10b80 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61  THREAD configura
10b90 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
10ba0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
10bb0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
10bc0 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ED]] <dt>SQLITE_
10bd0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
10be0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
10bf0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
10c00 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
10c10 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
10c20 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
10c30 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
10c40 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49  to Serialized. I
10c50 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
10c60 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c  his option enabl
10c70 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65  es.** all mutexe
10c80 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20  s including the 
10c90 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74  recursive.** mut
10ca0 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  exes on [databas
10cb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
10cc0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
10cd0 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a  ement] objects..
10ce0 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20  ** In this mode 
10cf0 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65  (which is the de
10d00 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74  fault when SQLit
10d10 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
10d20 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  th.** [SQLITE_TH
10d30 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65  READSAFE=1]) the
10d40 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20   SQLite library 
10d50 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69  will itself seri
10d60 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20  alize access.** 
10d70 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  to [database con
10d80 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70  nections] and [p
10d90 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
10da0 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a  ts] so that the.
10db0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  ** application i
10dc0 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68  s free to use th
10dd0 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65  e same [database
10de0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20   connection] or 
10df0 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65  the.** same [pre
10e00 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
10e10 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68   in different th
10e20 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
10e30 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53  e time..** ^If S
10e40 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
10e50 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
10e60 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
10e70 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
10e80 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
10e90 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
10ea0 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
10eb0 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68  ssible to set th
10ec0 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e Serialized [th
10ed0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
10ee0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
10ef0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
10f00 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
10f10 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
10f20 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
10f30 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
10f40 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  D configuration 
10f50 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
10f60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10f70 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e  IG_MALLOC]] <dt>
10f80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
10f90 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
10fa0 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
10fb0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
10fc0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
10fd0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
10fe0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
10ff0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
11000 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
11010 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65  ure.  The argume
11020 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  nt specifies.** 
11030 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d  alternative low-
11040 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  level memory all
11050 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
11060 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
11070 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d  lace of.** the m
11080 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11090 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
110a0 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e  into SQLite.)^ ^
110b0 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20  SQLite makes.** 
110c0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
110d0 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74  copy of the cont
110e0 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
110f0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
11100 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65   structure.** be
11110 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65  fore the [sqlite
11120 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c  3_config()] call
11130 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a   returns.</dd>.*
11140 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11150 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d  NFIG_GETMALLOC]]
11160 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
11170 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74  IG_GETMALLOC</dt
11180 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
11190 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
111a0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
111b0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
111c0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
111d0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
111e0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
111f0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
11200 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
11210 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
11220 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
11230 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
11240 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  y defined memory
11250 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
11260 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
11270 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
11280 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
11290 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
112a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
112b0 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20  routines with a 
112c0 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d  wrapper that sim
112d0 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20  ulations memory 
112e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
112f0 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20  re or.** tracks 
11300 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f  memory usage, fo
11310 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e  r example. </dd>
11320 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11330 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11340 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11350 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f  NFIG_MEMSTATUS</
11360 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
11370 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73  s option takes s
11380 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
11390 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65  f type int, inte
113a0 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a  rpreted as a .**
113b0 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20   boolean, which 
113c0 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
113d0 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69  les the collecti
113e0 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c  on of memory all
113f0 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74  ocation .** stat
11400 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d  istics. ^(When m
11410 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11420 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11430 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a  disabled, the .*
11440 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69  * following SQLi
11450 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65  te interfaces be
11460 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69  come non-operati
11470 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a  onal:.**   <ul>.
11480 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
11490 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
114a0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
114b0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
114c0 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c  water()].**   <l
114d0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  i> [sqlite3_soft
114e0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
114f0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
11500 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a  te3_status()].**
11510 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d     </ul>)^.** ^M
11520 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
11530 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
11540 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  enabled by defau
11550 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65  lt unless SQLite
11560 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20   is.** compiled 
11570 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46  with [SQLITE_DEF
11580 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d  AULT_MEMSTATUS]=
11590 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  0 in which case 
115a0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
115b0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
115c0 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20  are disabled by 
115d0 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64  default..** </dd
115e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
115f0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
11600 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11610 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e  FIG_SCRATCH</dt>
11620 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
11630 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
11640 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
11650 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
11660 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
11670 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
11680 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72  .  There are thr
11690 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41  ee arguments:  A
116a0 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79   pointer an 8-by
116b0 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65  te.** aligned me
116c0 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d  mory buffer from
116d0 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74   which the scrat
116e0 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77  ch allocations w
116f0 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c  ill be.** drawn,
11700 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
11710 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  h scratch alloca
11720 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e  tion (sz),.** an
11730 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d the maximum nu
11740 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20  mber of scratch 
11750 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e  allocations (N).
11760 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75    The sz.** argu
11770 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d  ment must be a m
11780 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a  ultiple of 16..*
11790 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
117a0 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70  ment must be a p
117b0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62  ointer to an 8-b
117c0 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66  yte aligned buff
117d0 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73  er.** of at leas
117e0 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
117f0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
11800 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d  te will use no m
11810 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72  ore than two scr
11820 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72  atch buffers per
11830 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20   thread.  So.** 
11840 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20  N should be set 
11850 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70  to twice the exp
11860 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75  ected maximum nu
11870 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e  mber of threads.
11880 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
11890 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61   never require a
118a0 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20   scratch buffer 
118b0 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61  that is more tha
118c0 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65  n 6.** times the
118d0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73   database page s
118e0 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ize. ^If SQLite 
118f0 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69  needs needs addi
11900 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63  tional.** scratc
11910 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20  h memory beyond 
11920 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
11930 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75   by this configu
11940 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74  ration option, t
11950 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  hen .** [sqlite3
11960 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20  _malloc()] will 
11970 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69  be used to obtai
11980 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65  n the memory nee
11990 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ded.</dd>.**.** 
119a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
119b0 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e  PAGECACHE]] <dt>
119c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41  SQLITE_CONFIG_PA
119d0 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20  GECACHE</dt>.** 
119e0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
119f0 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
11a00 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
11a10 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
11a20 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68  an use for.** th
11a30 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
11a40 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64  cache with the d
11a50 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68  efault page cach
11a60 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
11a70 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66  .  .** This conf
11a80 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64  iguration should
11a90 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20   not be used if 
11aa0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
11ab0 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61  efine page.** ca
11ac0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
11ad0 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69  on is loaded usi
11ae0 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  ng the SQLITE_CO
11af0 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74  NFIG_PCACHE2 opt
11b00 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  ion..** There ar
11b10 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
11b20 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
11b30 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38  : A pointer to 8
11b40 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a  -byte aligned.**
11b50 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a   memory, the siz
11b60 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62  e of each page b
11b70 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20  uffer (sz), and 
11b80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
11b90 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20  ges (N)..** The 
11ba0 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  sz argument shou
11bb0 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f  ld be the size o
11bc0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61  f the largest da
11bd0 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28  tabase page.** (
11be0 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62  a power of two b
11bf0 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33  etween 512 and 3
11c00 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74  2768) plus a lit
11c10 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61  tle extra for ea
11c20 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65  ch.** page heade
11c30 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65  r.  ^The page he
11c40 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20  ader size is 20 
11c50 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65  to 40 bytes depe
11c60 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20  nding on.** the 
11c70 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72  host architectur
11c80 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c  e.  ^It is harml
11c90 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20  ess, apart from 
11ca0 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72  the wasted memor
11cb0 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a  y,.** to make sz
11cc0 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61   a little too la
11cd0 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a  rge.  The first.
11ce0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  ** argument shou
11cf0 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ld point to an a
11d00 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20  llocation of at 
11d10 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
11d20 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
11d30 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
11d40 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69  the memory provi
11d50 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ded by the first
11d60 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74   argument to sat
11d70 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f  isfy its.** memo
11d80 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65  ry needs for the
11d90 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74   first N pages t
11da0 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63  hat it adds to c
11db0 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74  ache.  ^If addit
11dc0 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61  ional.** page ca
11dd0 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65  che memory is ne
11de0 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74  eded beyond what
11df0 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
11e00 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65  this option, the
11e10 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73  n.** SQLite goes
11e20 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   to [sqlite3_mal
11e30 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61  loc()] for the a
11e40 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67  dditional storag
11e50 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20  e space..** The 
11e60 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66  pointer in the f
11e70 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
11e80 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64  st.** be aligned
11e90 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f   to an 8-byte bo
11ea0 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
11eb0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
11ec0 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
11ed0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64  be undefined.</d
11ee0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11ef0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20  E_CONFIG_HEAP]] 
11f00 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11f10 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  G_HEAP</dt>.** <
11f20 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
11f30 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
11f40 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
11f50 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  r that SQLite wi
11f60 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c  ll use.** for al
11f70 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63  l of its dynamic
11f80 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11f90 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20  on needs beyond 
11fa0 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a  those provided.*
11fb0 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45  * for by [SQLITE
11fc0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d  _CONFIG_SCRATCH]
11fd0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   and [SQLITE_CON
11fe0 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a  FIG_PAGECACHE]..
11ff0 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72  ** There are thr
12000 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e  ee arguments: An
12010 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
12020 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
12030 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75  emory,.** the nu
12040 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
12050 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66   the memory buff
12060 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69  er, and the mini
12070 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
12080 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ize..** ^If the 
12090 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
120a0 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
120b0 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  r) is NULL, then
120c0 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a   SQLite reverts.
120d0 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20  ** to using its 
120e0 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
120f0 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79  llocator (the sy
12100 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d  stem malloc() im
12110 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a  plementation),.*
12120 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72  * undoing any pr
12130 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f  ior invocation o
12140 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
12150 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74  _MALLOC].  ^If t
12160 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69  he.** memory poi
12170 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  nter is not NULL
12180 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c   and either [SQL
12190 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
121a0 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  S3] or.** [SQLIT
121b0 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
121c0 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  ] are defined, t
121d0 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74  hen the alternat
121e0 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ive memory.** al
121f0 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67  locator is engag
12200 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c  ed to handle all
12210 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f   of SQLites memo
12220 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
12230 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  eds..** The firs
12240 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
12250 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d  emory pointer) m
12260 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
12270 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62  o an 8-byte.** b
12280 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
12290 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
122a0 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  f SQLite will be
122b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54   undefined..** T
122c0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
122d0 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61  ation size is ca
122e0 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52  pped at 2**12. R
122f0 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73  easonable values
12300 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69  .** for the mini
12310 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
12320 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72  ize are 2**5 thr
12330 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a  ough 2**8.</dd>.
12340 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12350 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64  ONFIG_MUTEX]] <d
12360 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
12370 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
12380 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
12390 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
123a0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
123b0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
123c0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
123d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
123e0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
123f0 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67  ucture.  The arg
12400 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a  ument specifies.
12410 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c  ** alternative l
12420 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72  ow-level mutex r
12430 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
12440 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74  ed in place.** t
12450 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  he mutex routine
12460 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
12470 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20  ite.)^  ^SQLite 
12480 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
12490 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f  the.** content o
124a0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
124b0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
124c0 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74  ructure before t
124d0 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  he call to.** [s
124e0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
124f0 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51   returns. ^If SQ
12500 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
12510 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
12520 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
12530 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
12540 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
12550 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
12560 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75  ** the entire mu
12570 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d  texing subsystem
12580 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d   is omitted from
12590 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68   the build and h
125a0 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ence calls to.**
125b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
125c0 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c  ()] with the SQL
125d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
125e0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
125f0 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65  ption will.** re
12600 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
12610 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  OR].</dd>.**.** 
12620 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12630 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53  GETMUTEX]] <dt>S
12640 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12650 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  MUTEX</dt>.** <d
12660 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
12670 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
12680 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
12690 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
126a0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
126b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
126c0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
126d0 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20  ucture.  The.** 
126e0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d  [sqlite3_mutex_m
126f0 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63  ethods].** struc
12700 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77  ture is filled w
12710 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c  ith the currentl
12720 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20  y defined mutex 
12730 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
12740 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
12750 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
12760 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
12770 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  utex allocation.
12780 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68  ** routines with
12790 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20   a wrapper used 
127a0 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75  to track mutex u
127b0 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d  sage for perform
127c0 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e  ance.** profilin
127d0 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f  g or testing, fo
127e0 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66  r example.   ^If
127f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12800 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
12810 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
12820 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
12830 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
12840 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
12850 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65  en.** the entire
12860 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73   mutexing subsys
12870 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66  tem is omitted f
12880 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e  rom the build an
12890 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f  d hence calls to
128a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
128b0 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20  fig()] with the 
128c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
128d0 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61  TMUTEX configura
128e0 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c  tion option will
128f0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
12900 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a  TE_ERROR].</dd>.
12910 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12920 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
12930 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12940 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
12950 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
12960 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
12970 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
12980 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
12990 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
129a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
129b0 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
129c0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
129d0 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
129e0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
129f0 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
12a00 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
12a10 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
12a20 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
12a30 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
12a40 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
12a50 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
12a60 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
12a70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12a80 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
12a90 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
12aa0 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
12ab0 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
12ac0 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
12ad0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
12ae0 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
12af0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
12b00 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
12b10 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
12b20 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
12b30 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
12b40 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
12b50 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ^ </dd>.**.** [[
12b60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
12b70 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49  ACHE2]] <dt>SQLI
12b80 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
12b90 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  2</dt>.** <dd> ^
12ba0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
12bb0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
12bc0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
12bd0 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e  pointer to.** an
12be0 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65   [sqlite3_pcache
12bf0 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63  _methods2] objec
12c00 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20  t.  This object 
12c10 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e  specifies the in
12c20 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20  terface.** to a 
12c30 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68  custom page cach
12c40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
12c50 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b  .)^  ^SQLite mak
12c60 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
12c70 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75  .** object and u
12c80 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20  ses it for page 
12c90 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  cache memory all
12ca0 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a  ocations.</dd>.*
12cb0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
12cc0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d  NFIG_GETPCACHE2]
12cd0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12ce0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f  FIG_GETPCACHE2</
12cf0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
12d00 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
12d10 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
12d20 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
12d30 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
12d40 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
12d50 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20  thods2] object. 
12d60 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f   SQLite copies o
12d70 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
12d80 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c   page cache impl
12d90 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20  ementation into 
12da0 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c  that object.)^ <
12db0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12dc0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d  ITE_CONFIG_LOG]]
12dd0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12de0 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  IG_LOG</dt>.** <
12df0 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f  dd> ^The SQLITE_
12e00 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
12e10 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
12e20 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
12e30 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
12e40 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
12e50 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
12e60 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
12e70 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
12e80 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
12e90 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
12ea0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
12eb0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
12ec0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
12ed0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
12ee0 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
12ef0 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
12f00 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
12f10 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
12f20 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
12f30 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
12f40 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
12f50 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
12f60 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
12f70 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
12f80 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
12f90 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
12fa0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
12fb0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
12fc0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
12fd0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
12fe0 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
12ff0 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
13000 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
13010 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
13020 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
13030 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
13040 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
13050 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
13060 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
13070 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
13080 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
13090 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
130a0 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
130b0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
130c0 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
130d0 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
130e0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
130f0 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
13100 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
13110 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
13120 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
13130 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
13140 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
13150 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
13160 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
13170 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
13180 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
13190 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
131a0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
131b0 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
131c0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
131d0 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
131e0 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
131f0 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
13200 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
13210 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
13220 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
13230 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
13240 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
13250 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  RI]] <dt>SQLITE_
13260 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64  CONFIG_URI.** <d
13270 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  d> This option t
13280 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
13290 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
132a0 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c  nt. If non-zero,
132b0 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e   then.** URI han
132c0 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
132d0 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68  y enabled. If th
132e0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a  e parameter is z
132f0 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61  ero, then URI ha
13300 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f  ndling.** is glo
13310 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20  bally disabled. 
13320 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
13330 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
13340 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d  led, all filenam
13350 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20  es.** passed to 
13360 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
13370 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
13380 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
13390 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  open16()] or.** 
133a0 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
133b0 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f  t of [ATTACH] co
133c0 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72  mmands are inter
133d0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20  preted as URIs, 
133e0 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
133f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
13400 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
13410 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65  _URI] flag is se
13420 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  t when the datab
13430 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
13440 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20  n is opened. If 
13450 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  it is globally d
13460 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d  isabled, filenam
13470 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69  es are.** only i
13480 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
13490 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45  Is if the SQLITE
134a0 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69  _OPEN_URI flag i
134b0 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a  s set when the.*
134c0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
134d0 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
134e0 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49   By default, URI
134f0 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
13500 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
13510 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
13520 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
13530 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
13540 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
13550 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
13560 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a  mbol defined..**
13570 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13580 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
13590 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
135a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
135b0 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
135c0 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74  ** <dd> This opt
135d0 69 6f 6e 20 74 61 6b 73 20 61 20 73 69 6e 67 6c  ion taks a singl
135e0 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d 65  e integer argume
135f0 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74 65  nt which is inte
13600 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61 20  rpreted as.** a 
13610 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72  boolean in order
13620 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
13630 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66  sable the use of
13640 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65   covering indice
13650 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61  s for.** full ta
13660 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68 65  ble scans in the
13670 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65 72   query optimizer
13680 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 73  .  The default s
13690 65 74 74 69 6e 67 20 69 73 20 64 65 74 65 72 6d  etting is determ
136a0 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b  ined.** by the [
136b0 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56  SQLITE_ALLOW_COV
136c0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
136d0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
136e0 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e  ption, or is "on
136f0 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63 6f 6d  ".** if that com
13700 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
13710 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20   is omitted..** 
13720 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 64  The ability to d
13730 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
13740 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
13750 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c  es for full tabl
13760 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65  e scans.** is be
13770 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72  cause some incor
13780 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c 65 67  rectly coded leg
13790 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  acy applications
137a0 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63 74 69   might malfuncti
137b0 6f 6e 0a 2a 2a 20 6d 61 6c 66 75 6e 63 74 69 6f  on.** malfunctio
137c0 6e 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d  n when the optim
137d0 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  ization is enabl
137e0 65 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74  ed.  Providing t
137f0 68 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a  he ability to.**
13800 20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74   disable the opt
13810 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73  imization allows
13820 20 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67   the older, bugg
13830 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  y application co
13840 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69  de to work.** wi
13850 74 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65  thout change eve
13860 6e 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72  n with newer ver
13870 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
13880 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13890 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20  CONFIG_PCACHE]] 
138a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
138b0 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c  GETPCACHE]].** <
138c0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
138d0 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49  _PCACHE and SQLI
138e0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
138f0 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73  CHE.** <dd> Thes
13900 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62  e options are ob
13910 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c  solete and shoul
13920 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79  d not be used by
13930 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68   new code..** Th
13940 65 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20  ey are retained 
13950 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
13960 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20  mpatibility but 
13970 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a  are now no-ops..
13980 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dl>.**.** [
13990 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
139a0 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  QLLOG]].** <dt>S
139b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c  QLITE_CONFIG_SQL
139c0 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20  LOG.** <dd>This 
139d0 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61  option is only a
139e0 76 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69  vailable if sqli
139f0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
13a00 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
13a10 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 20  E_ENABLE_SQLLOG 
13a20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61  pre-processor ma
13a30 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68 65  cro defined. The
13a40 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
13a50 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70  should.** be a p
13a60 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e 63  ointer to a func
13a70 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f 69  tion of type voi
13a80 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
13a90 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  e3*,const char*,
13aa0 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65   int)..** The se
13ab0 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20 6f  cond should be o
13ac0 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e 20  f type (void*). 
13ad0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  The callback is 
13ae0 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20 6c  invoked by the l
13af0 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72  ibrary.** in thr
13b00 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72 63  ee separate circ
13b10 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e 74  umstances, ident
13b20 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61 6c  ified by the val
13b30 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
13b40 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
13b50 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f 75  eter. If the fou
13b60 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
13b70 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74   0, then the dat
13b80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13b90 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74 68  .** passed as th
13ba0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
13bb0 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20  t has just been 
13bc0 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69 72  opened. The thir
13bd0 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f  d argument.** po
13be0 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65 72  ints to a buffer
13bf0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
13c00 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69 6e  name of the main
13c10 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20   database file. 
13c20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68  If the.** fourth
13c30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31 2c   parameter is 1,
13c40 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   then the SQL st
13c50 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68 65  atement that the
13c60 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
13c70 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68 61  .** points to ha
13c80 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65 63  s just been exec
13c90 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68 65  uted. Or, if the
13ca0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
13cb0 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20  r is 2, then.** 
13cc0 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62  the connection b
13cd0 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20 74  eing passed as t
13ce0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
13cf0 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c 6f  ter is being clo
13d00 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72  sed. The.** thir
13d10 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  d parameter is p
13d20 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68  assed NULL In th
13d30 69 73 20 63 61 73 65 2e 0a 2a 2a 20 3c 2f 64 6c  is case..** </dl
13d40 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
13d50 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
13d60 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
13d70 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
13d80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
13d90 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
13da0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
13db0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
13dc0 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
13dd0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
13de0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
13df0 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
13e00 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
13e10 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
13e20 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13e30 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
13e40 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
13e50 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
13e60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
13e70 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
13e80 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
13e90 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
13ea0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
13eb0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
13ec0 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
13ed0 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
13ee0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13ef0 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
13f00 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
13f10 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
13f20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
13f30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
13f40 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
13f50 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
13f60 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
13f70 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
13f80 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
13f90 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
13fa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
13fb0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
13fc0 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
13fd0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
13fe0 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
13ff0 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
14000 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
14010 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
14020 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
14030 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
14040 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
14050 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
14060 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14070 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
14080 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  4  /* no-op */.#
14090 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
140a0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
140b0 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    15  /* no-op *
140c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
140d0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
140e0 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
140f0 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  c, void* */.#def
14100 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14110 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31  G_URI          1
14120 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  7  /* int */.#de
14130 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
14140 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20  IG_PCACHE2      
14150 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  18  /* sqlite3_p
14160 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
14170 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14180 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
14190 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c  HE2   19  /* sql
141a0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
141b0 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
141c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43   SQLITE_CONFIG_C
141d0 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
141e0 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f  AN 20  /* int */
141f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
14200 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20  CONFIG_SQLLOG   
14210 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c      21  /* xSqll
14220 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a  og, void* */../*
14230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
14240 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
14250 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  n Configuration 
14260 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  Options.**.** Th
14270 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
14280 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
14290 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
142a0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
142b0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
142c0 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
142d0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  d argument to th
142e0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
142f0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
14300 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e  e..**.** New con
14310 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14320 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  ns may be added 
14330 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
14340 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  es of SQLite..**
14350 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67   Existing config
14360 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
14370 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74  might be discont
14380 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74  inued.  Applicat
14390 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63  ions.** should c
143a0 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20  heck the return 
143b0 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74  code from [sqlit
143c0 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
143d0 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
143e0 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
143f0 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c  rked.  ^The [sql
14400 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
14410 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  ] interface will
14420 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e   return a.** non
14430 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64  -zero [error cod
14440 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69  e] if a disconti
14450 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72  nued or unsuppor
14460 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted configuratio
14470 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69  n option.** is i
14480 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64  nvoked..**.** <d
14490 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  l>.** <dt>SQLITE
144a0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
144b0 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  IDE</dt>.** <dd>
144c0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
144d0 6b 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69  kes three additi
144e0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74  onal arguments t
144f0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
14500 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65  e .** [lookaside
14510 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
14520 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  r] configuration
14530 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61   for the [databa
14540 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a  se connection]..
14550 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
14560 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72  gument (the thir
14570 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  d parameter to [
14580 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
14590 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69  g()] is a.** poi
145a0 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
145b0 20 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66   buffer to use f
145c0 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  or lookaside mem
145d0 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ory..** ^The fir
145e0 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65  st argument afte
145f0 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43  r the SQLITE_DBC
14600 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
14610 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e  verb.** may be N
14620 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73  ULL in which cas
14630 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  e SQLite will al
14640 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f  locate the.** lo
14650 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69  okaside buffer i
14660 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c  tself using [sql
14670 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20  ite3_malloc()]. 
14680 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
14690 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
146a0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
146b0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
146c0 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61  t.  ^The third a
146d0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
146e0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74  umber of.** slot
146f0 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  s.  The size of 
14700 74 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68  the buffer in th
14710 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14720 20 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72   must be greater
14730 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61   than.** or equa
14740 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74  l to the product
14750 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61   of the second a
14760 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  nd third argumen
14770 74 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a  ts.  The buffer.
14780 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  ** must be align
14790 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
147a0 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74  boundary.  ^If t
147b0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
147c0 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f  nt to.** SQLITE_
147d0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
147e0 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74  DE is not a mult
147f0 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73  iple of 8, it is
14800 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72   internally.** r
14810 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74  ounded down to t
14820 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20  he next smaller 
14830 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20  multiple of 8.  
14840 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  ^(The lookaside 
14850 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67  memory.** config
14860 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61  uration for a da
14870 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14880 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
14890 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a  anged when that.
148a0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
148b0 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75   not currently u
148c0 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  sing lookaside m
148d0 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68  emory, or in oth
148e0 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e  er words.** when
148f0 20 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61   the "current va
14900 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79  lue" returned by
14910 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  .** [sqlite3_db_
14920 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54  status](D,[SQLIT
14930 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
14940 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f  DE],...) is zero
14950 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74  ..** Any attempt
14960 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
14970 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
14980 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68  configuration wh
14990 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  en lookaside.** 
149a0 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65  memory is in use
149b0 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66   leaves the conf
149c0 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e  iguration unchan
149d0 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ged and returns 
149e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
149f0 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
14a00 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
14a10 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c  FIG_ENABLE_FKEY<
14a20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
14a30 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
14a40 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
14a50 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72  isable the enfor
14a60 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f  cement of.** [fo
14a70 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72  reign key constr
14a80 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73  aints].  There s
14a90 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64  hould be two add
14aa0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
14ab0 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  s..** The first 
14ac0 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69  argument is an i
14ad0 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
14ae0 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20  0 to disable FK 
14af0 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20  enforcement,.** 
14b00 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
14b10 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
14b20 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  t or negative to
14b30 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63   leave FK enforc
14b40 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67  ement.** unchang
14b50 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ed.  The second 
14b60 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
14b70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
14b80 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a  eger into which.
14b90 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20  ** is written 0 
14ba0 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65  or 1 to indicate
14bb0 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f   whether FK enfo
14bc0 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f  rcement is off o
14bd0 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  r on.** followin
14be0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
14bf0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14c00 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
14c10 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
14c20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46  which case the F
14c30 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65  K enforcement se
14c40 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
14c50 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
14c60 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
14c70 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
14c80 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a  LE_TRIGGER</dt>.
14c90 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
14ca0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
14cb0 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c  enable or disabl
14cc0 65 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  e [CREATE TRIGGE
14cd0 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a  R | triggers]..*
14ce0 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62  * There should b
14cf0 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
14d00 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
14d10 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14d20 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
14d30 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
14d40 73 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a  sable triggers,.
14d50 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
14d60 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f  nable triggers o
14d70 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
14d80 61 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20  ave the setting 
14d90 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68  unchanged..** Th
14da0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
14db0 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
14dc0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
14dd0 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
14de0 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
14df0 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
14e00 72 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64  r triggers are d
14e10 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c  isabled or enabl
14e20 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ed.** following 
14e30 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20  this call.  The 
14e40 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14e50 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70   may be a NULL p
14e60 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68  ointer, in.** wh
14e70 69 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69  ich case the tri
14e80 67 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20  gger setting is 
14e90 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63  not reported bac
14ea0 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  k. </dd>.**.** <
14eb0 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
14ec0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
14ed0 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20  LOOKASIDE       
14ee0 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69  1001  /* void* i
14ef0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
14f00 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
14f10 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20  G_ENABLE_FKEY   
14f20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69    1002  /* int i
14f30 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nt* */.#define S
14f40 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
14f50 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31  NABLE_TRIGGER  1
14f60 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  003  /* int int*
14f70 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   */.../*.** CAPI
14f80 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20  3REF: Enable Or 
14f90 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64  Disable Extended
14fa0 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
14fb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
14fc0 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
14fd0 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65  _codes() routine
14fe0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
14ff0 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74  bles the.** [ext
15000 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
15010 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53  es] feature of S
15020 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65  QLite. ^The exte
15030 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  nded result.** c
15040 6f 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65  odes are disable
15050 64 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72  d by default for
15060 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70   historical comp
15070 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51  atibility..*/.SQ
15080 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
15090 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
150a0 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74  sult_codes(sqlit
150b0 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b  e3*, int onoff);
150c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
150d0 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f  : Last Insert Ro
150e0 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20  wid.**.** ^Each 
150f0 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69  entry in an SQLi
15100 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75  te table has a u
15110 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
15120 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
15130 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
15140 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
15150 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
15160 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
15170 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
15180 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
15190 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
151a0 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
151b0 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
151c0 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
151d0 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
151e0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
151f0 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
15200 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
15210 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
15220 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
15230 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
15240 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
15250 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
15260 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  id..**.** ^This 
15270 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
15280 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
15290 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a  he most recent.*
152a0 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
152b0 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64  SERT] into the d
152c0 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65  atabase from the
152d0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
152e0 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ction].** in the
152f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
15300 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65 20    ^As of SQLite 
15310 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74  version 3.7.7, t
15320 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20  his routines.** 
15330 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73 74  records the last
15340 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f 66   insert rowid of
15350 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20 74   both ordinary t
15360 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74 75  ables and [virtu
15370 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e  al tables]..** ^
15380 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c  If no successful
15390 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61   [INSERT]s.** ha
153a0 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
153b0 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73   on that databas
153c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65  e connection, ze
153d0 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
153e0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49  **.** ^(If an [I
153f0 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69  NSERT] occurs wi
15400 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f  thin a trigger o
15410 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74  r within a [virt
15420 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65  ual table].** me
15430 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20  thod, then this 
15440 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74  routine will ret
15450 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20  urn the [rowid] 
15460 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a  of the inserted.
15470 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61  ** row as long a
15480 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  s the trigger or
15490 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d   virtual table m
154a0 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67  ethod is running
154b0 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68  ..** But once th
154c0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
154d0 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f  tual table metho
154e0 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75  d ends, the valu
154f0 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62  e returned .** b
15500 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72  y this routine r
15510 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69  everts to what i
15520 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65  t was before the
15530 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
15540 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74  ual.** table met
15550 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a  hod began.)^.**.
15560 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20  ** ^An [INSERT] 
15570 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74  that fails due t
15580 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  o a constraint v
15590 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20  iolation is not 
155a0 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  a.** successful 
155b0 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65  [INSERT] and doe
155c0 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
155d0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
155e0 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  by this.** routi
155f0 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52  ne.  ^Thus INSER
15600 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52  T OR FAIL, INSER
15610 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53  T OR IGNORE, INS
15620 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c  ERT OR ROLLBACK,
15630 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f  .** and INSERT O
15640 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20  R ABORT make no 
15650 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72  changes to the r
15660 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
15670 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77  his.** routine w
15680 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74  hen their insert
15690 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68  ion fails.  ^(Wh
156a0 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  en INSERT OR REP
156b0 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65  LACE.** encounte
156c0 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  rs a constraint 
156d0 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f  violation, it do
156e0 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68  es not fail.  Th
156f0 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74  e.** INSERT cont
15700 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74  inues to complet
15710 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69  ion after deleti
15720 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75  ng rows that cau
15730 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74  sed.** the const
15740 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f  raint problem so
15750 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
15760 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63  CE will always c
15770 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74  hange.** the ret
15780 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
15790 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a  s interface.)^.*
157a0 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75  *.** ^For the pu
157b0 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72  rposes of this r
157c0 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45  outine, an [INSE
157d0 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65  RT] is considere
157e0 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65  d to.** be succe
157f0 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74  ssful even if it
15800 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79   is subsequently
15810 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a   rolled back..**
15820 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f  .** This functio
15830 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20  n is accessible 
15840 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  to SQL statement
15850 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61  s via the.** [la
15860 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
15870 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
15880 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
15890 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66  rate thread perf
158a0 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45  orms a new [INSE
158b0 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a  RT] on the same.
158c0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
158d0 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65  ection while the
158e0 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
158f0 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a  nsert_rowid()].*
15900 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  * function is ru
15910 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63  nning and thus c
15920 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20  hanges the last 
15930 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a  insert [rowid],.
15940 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ** then the valu
15950 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  e returned by [s
15960 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
15970 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a  rt_rowid()] is.*
15980 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  * unpredictable 
15990 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71  and might not eq
159a0 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f  ual either the o
159b0 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a  ld or the new.**
159c0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f   last insert [ro
159d0 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  wid]..*/.SQLITE_
159e0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
159f0 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  4 sqlite3_last_i
15a00 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69  nsert_rowid(sqli
15a10 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
15a20 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68  PI3REF: Count Th
15a30 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73  e Number Of Rows
15a40 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20   Modified.**.** 
15a50 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
15a60 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
15a70 72 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f  r of database ro
15a80 77 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61  ws that were cha
15a90 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72  nged.** or inser
15aa0 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62  ted or deleted b
15ab0 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  y the most recen
15ac0 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51  tly completed SQ
15ad0 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f  L statement.** o
15ae0 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  n the [database 
15af0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
15b00 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72  ified by the fir
15b10 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  st parameter..**
15b20 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20   ^(Only changes 
15b30 74 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c  that are directl
15b40 79 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  y specified by t
15b50 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50  he [INSERT], [UP
15b60 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45  DATE],.** or [DE
15b70 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20  LETE] statement 
15b80 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75  are counted.  Au
15b90 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20  xiliary changes 
15ba0 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69  caused by.** tri
15bb0 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67  ggers or [foreig
15bc0 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61  n key actions] a
15bd0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29  re not counted.)
15be0 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71  ^ Use the.** [sq
15bf0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
15c00 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20  ges()] function 
15c10 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61  to find the tota
15c20 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e  l number of chan
15c30 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67  ges.** including
15c40 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
15c50 62 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20  by triggers and 
15c60 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
15c70 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e  ons..**.** ^Chan
15c80 67 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68  ges to a view th
15c90 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64  at are simulated
15ca0 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20   by an [INSTEAD 
15cb0 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61  OF trigger].** a
15cc0 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20  re not counted. 
15cd0 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65   Only real table
15ce0 20 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75   changes are cou
15cf0 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20  nted..**.** ^(A 
15d00 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20  "row change" is 
15d10 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69  a change to a si
15d20 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69  ngle row of a si
15d30 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61  ngle table.** ca
15d40 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52  used by an INSER
15d50 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50  T, DELETE, or UP
15d60 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20  DATE statement. 
15d70 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72   Rows that.** ar
15d80 65 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64  e changed as sid
15d90 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45  e effects of [RE
15da0 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
15db0 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a  t resolution,.**
15dc0 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54   rollback, ABORT
15dd0 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52   processing, [DR
15de0 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79  OP TABLE], or by
15df0 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   any other.** me
15e00 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20  chanisms do not 
15e10 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20  count as direct 
15e20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a  row changes.)^.*
15e30 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20  *.** A "trigger 
15e40 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63  context" is a sc
15e50 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e  ope of execution
15e60 20 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64   that begins and
15e70 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68  .** ends with th
15e80 65 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43  e script of a [C
15e90 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
15ea0 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f  trigger]. .** Mo
15eb0 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  st SQL statement
15ec0 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74  s are.** evaluat
15ed0 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  ed outside of an
15ee0 79 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73  y trigger.  This
15ef0 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76   is the "top lev
15f00 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63  el".** trigger c
15f10 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72  ontext.  If a tr
15f20 69 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d  igger fires from
15f30 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
15f40 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72  a.** new trigger
15f50 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65   context is ente
15f60 72 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61  red for the dura
15f70 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65  tion of that one
15f80 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75  .** trigger.  Su
15f90 62 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65  btriggers create
15fa0 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72   subcontexts for
15fb0 20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e   their duration.
15fc0 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
15fd0 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
15fe0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   or [sqlite3_ste
15ff0 70 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79  p()] recursively
16000 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65   does.** not cre
16010 61 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65  ate a new trigge
16020 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a  r context..**.**
16030 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
16040 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
16050 65 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77  er of direct row
16060 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a   changes in the.
16070 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  ** most recent I
16080 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
16090 72 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65  r DELETE stateme
160a0 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  nt within the sa
160b0 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  me.** trigger co
160c0 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
160d0 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20  us, when called 
160e0 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76  from the top lev
160f0 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f  el, this functio
16100 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  n returns the.**
16110 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
16120 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
16130 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50  ecent INSERT, UP
16140 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
16150 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63  ** that also occ
16160 75 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70  urred at the top
16170 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69   level.  ^(Withi
16180 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20  n the body of a 
16190 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20  trigger,.** the 
161a0 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
161b0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  ) interface can 
161c0 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e  be called to fin
161d0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  d the number of.
161e0 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ** changes in th
161f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
16200 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54  completed INSERT
16210 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
16220 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ETE.** statement
16230 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79   within the body
16240 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69   of the same tri
16250 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  gger..** However
16260 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74  , the number ret
16270 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69  urned does not i
16280 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a  nclude changes.*
16290 2a 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74  * caused by subt
162a0 72 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68  riggers since th
162b0 6f 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f  ose have their o
162c0 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a  wn context.)^.**
162d0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65  .** See also the
162e0 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f   [sqlite3_total_
162f0 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72  changes()] inter
16300 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f  face, the.** [co
16310 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67  unt_changes prag
16320 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68  ma], and the [ch
16330 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63  anges() SQL func
16340 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  tion]..**.** If 
16350 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
16360 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  d makes changes 
16370 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  on the same data
16380 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
16390 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  ** while [sqlite
163a0 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  3_changes()] is 
163b0 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
163c0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
163d0 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ** is unpredicta
163e0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
163f0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  ingful..*/.SQLIT
16400 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
16410 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65  3_changes(sqlite
16420 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
16430 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62  3REF: Total Numb
16440 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66  er Of Rows Modif
16450 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ied.**.** ^This 
16460 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
16470 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
16480 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ow changes cause
16490 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a  d by [INSERT],.*
164a0 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44  * [UPDATE] or [D
164b0 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74  ELETE] statement
164c0 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74  s since the [dat
164d0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
164e0 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a  ] was opened..**
164f0 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74   ^(The count ret
16500 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
16510 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
16520 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68   includes all ch
16530 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c  anges.** from al
16540 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45  l [CREATE TRIGGE
16550 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e  R | trigger] con
16560 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65  texts and change
16570 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f  s made by.** [fo
16580 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
16590 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  s]. However,.** 
165a0 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  the count does n
165b0 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67  ot include chang
165c0 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65  es used to imple
165d0 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63  ment [REPLACE] c
165e0 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64  onstraints,.** d
165f0 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41  o rollbacks or A
16600 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c  BORT processing,
16610 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d   or [DROP TABLE]
16620 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68   processing.  Th
16630 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20  e.** count does 
16640 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73  not include rows
16650 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66   of views that f
16660 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20  ire an [INSTEAD 
16670 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20  OF trigger],.** 
16680 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e  though if the IN
16690 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
166a0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
166b0 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65  f its own, those
166c0 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65   changes .** are
166d0 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e   counted.)^.** ^
166e0 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61  The sqlite3_tota
166f0 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63  l_changes() func
16700 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20  tion counts the 
16710 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20  changes as soon 
16720 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d  as.** the statem
16730 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74  ent that makes t
16740 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64  hem is completed
16750 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65   (when the state
16760 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69  ment handle.** i
16770 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  s passed to [sql
16780 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
16790 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
167a0 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65  ze()])..**.** Se
167b0 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69  e also the [sqli
167c0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
167d0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a  nterface, the.**
167e0 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20   [count_changes 
167f0 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65  pragma], and the
16800 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28   [total_changes(
16810 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e  ) SQL function].
16820 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61  .**.** If a sepa
16830 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65  rate thread make
16840 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65  s changes on the
16850 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
16860 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69  onnection.** whi
16870 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  le [sqlite3_tota
16880 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20  l_changes()] is 
16890 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65  running then the
168a0 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e   value.** return
168b0 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61  ed is unpredicta
168c0 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e  ble and not mean
168d0 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  ingful..*/.SQLIT
168e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
168f0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
16900 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
16910 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
16920 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
16930 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a  ning Query.**.**
16940 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
16950 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
16960 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
16970 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
16980 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
16990 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
169a0 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
169b0 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
169c0 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
169d0 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
169e0 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
169f0 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
16a00 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
16a10 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
16a20 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
16a30 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
16a40 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
16a50 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
16a60 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
16a70 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
16a80 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
16a90 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
16aa0 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
16ab0 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
16ac0 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
16ad0 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
16ae0 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
16af0 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
16b00 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
16b10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16b20 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
16b30 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
16b40 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
16b50 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
16b60 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
16b70 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
16b80 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
16b90 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
16ba0 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
16bb0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
16bc0 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
16bd0 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
16be0 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
16bf0 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
16c00 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
16c10 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
16c20 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
16c30 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
16c40 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
16c50 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
16c60 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
16c70 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
16c80 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
16c90 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
16ca0 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
16cb0 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
16cc0 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
16cd0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
16ce0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
16cf0 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
16d00 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
16d10 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
16d20 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
16d30 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
16d40 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
16d50 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
16d60 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
16d70 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
16d80 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
16d90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16da0 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
16db0 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
16dc0 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
16dd0 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
16de0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
16df0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
16e00 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
16e10 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
16e20 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
16e30 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
16e40 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
16e50 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
16e60 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
16e70 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
16e80 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
16e90 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
16ea0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
16eb0 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
16ec0 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
16ed0 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
16ee0 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
16ef0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
16f00 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
16f10 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
16f20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
16f30 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
16f40 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
16f50 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
16f60 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
16f70 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
16f80 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
16f90 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
16fa0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
16fb0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
16fc0 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
16fd0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
16fe0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
16ff0 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
17000 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
17010 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
17020 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
17030 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
17040 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
17050 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
17060 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  d sqlite3_interr
17070 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  upt(sqlite3*);..
17080 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17090 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
170a0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73  SQL Statement Is
170b0 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20   Complete.**.** 
170c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
170d0 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67  re useful during
170e0 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e   command-line in
170f0 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65  put to determine
17100 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   if the.** curre
17110 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78  ntly entered tex
17120 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20  t seems to form 
17130 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
17140 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69  tatement or.** i
17150 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70  f additional inp
17160 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66  ut is needed bef
17170 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20  ore sending the 
17180 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c  text into.** SQL
17190 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e  ite for parsing.
171a0 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65    ^These routine
171b0 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68  s return 1 if th
171c0 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a  e input string.*
171d0 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20  * appears to be 
171e0 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73  a complete SQL s
171f0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74  tatement.  ^A st
17200 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65  atement is judge
17210 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c  d to be.** compl
17220 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77  ete if it ends w
17230 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20  ith a semicolon 
17240 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74  token and is not
17250 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a   a prefix of a.*
17260 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52  * well-formed CR
17270 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61  EATE TRIGGER sta
17280 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f  tement.  ^Semico
17290 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d  lons that are em
172a0 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a  bedded within.**
172b0 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73   string literals
172c0 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74   or quoted ident
172d0 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63  ifier names or c
172e0 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a  omments are not.
172f0 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74  ** independent t
17300 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20  okens (they are 
17310 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65  part of the toke
17320 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20  n in which they 
17330 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29  are.** embedded)
17340 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74   and thus do not
17350 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74   count as a stat
17360 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72  ement terminator
17370 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a  .  ^Whitespace.*
17380 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74  * and comments t
17390 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66  hat follow the f
173a0 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61  inal semicolon a
173b0 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  re ignored..**.*
173c0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
173d0 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68  s return 0 if th
173e0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69  e statement is i
173f0 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20  ncomplete.  ^If 
17400 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  a.** memory allo
17410 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68  cation fails, th
17420 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20  en SQLITE_NOMEM 
17430 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
17440 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
17450 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20  es do not parse 
17460 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
17470 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20  ts thus.** will 
17480 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61  not detect synta
17490 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65  ctically incorre
174a0 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ct SQL..**.** ^(
174b0 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f  If SQLite has no
174c0 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a  t been initializ
174d0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
174e0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20  3_initialize()] 
174f0 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76  prior .** to inv
17500 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f  oking sqlite3_co
17510 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20  mplete16() then 
17520 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
17530 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a  ze() is invoked.
17540 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
17550 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   by sqlite3_comp
17560 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68  lete16().  If th
17570 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  at initializatio
17580 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e  n fails,.** then
17590 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
175a0 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
175b0 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c  omplete16() will
175c0 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20   be non-zero.** 
175d0 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
175e0 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
175f0 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f   input SQL is co
17600 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  mplete.)^.**.** 
17610 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
17620 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29  lite3_complete()
17630 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
17640 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
17650 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  TF-8 string..**.
17660 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
17670 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
17680 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61  e16()] must be a
17690 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
176a0 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
176b0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
176c0 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54   order..*/.SQLIT
176d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
176e0 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
176f0 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c   char *sql);.SQL
17700 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
17710 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63  te3_complete16(c
17720 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b  onst void *sql);
17730 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
17740 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c  : Register A Cal
17750 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20  lback To Handle 
17760 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f  SQLITE_BUSY Erro
17770 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
17780 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61  outine sets a ca
17790 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
177a0 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e  that might be in
177b0 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a  voked whenever.*
177c0 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20  * an attempt is 
177d0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64  made to open a d
177e0 61 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68  atabase table th
177f0 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  at another threa
17800 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20  d.** or process 
17810 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a  has locked..**.*
17820 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63  * ^If the busy c
17830 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c  allback is NULL,
17840 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55   then [SQLITE_BU
17850 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
17860 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
17870 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
17880 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e  ediately upon en
17890 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c  countering the l
178a0 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75  ock.  ^If the bu
178b0 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  sy callback.** i
178c0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
178d0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69   the callback mi
178e0 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
178f0 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  ith two argument
17900 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  s..**.** ^The fi
17910 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
17920 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
17930 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
17940 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20  e void* pointer 
17950 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20  which.** is the 
17960 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
17970 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68  o sqlite3_busy_h
17980 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20  andler().  ^The 
17990 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
179a0 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68  to.** the busy h
179b0 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
179c0 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
179d0 20 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20   times that the 
179e0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73  busy handler has
179f0 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64  .** been invoked
17a00 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e   for this lockin
17a10 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
17a20 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
17a30 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
17a40 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
17a50 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
17a60 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
17a70 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
17a80 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
17a90 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
17aa0 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75  BLOCKED] is retu
17ab0 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  rned..** ^If the
17ac0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
17ad0 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  s non-zero, then
17ae0 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74   another attempt
17af0 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  .** is made to o
17b00 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
17b10 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64   for reading and
17b20 20 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61   the cycle repea
17b30 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ts..**.** The pr
17b40 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79  esence of a busy
17b50 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f   handler does no
17b60 74 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  t guarantee that
17b70 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f   it will be invo
17b80 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72  ked.** when ther
17b90 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e  e is lock conten
17ba0 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65  tion. ^If SQLite
17bb0 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74   determines that
17bc0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
17bd0 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f  sy.** handler co
17be0 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20  uld result in a 
17bf0 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c  deadlock, it wil
17c00 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72  l go ahead and r
17c10 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55  eturn [SQLITE_BU
17c20 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  SY].** or [SQLIT
17c30 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
17c40 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f   instead of invo
17c50 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61  king the busy ha
17c60 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
17c70 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
17c80 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
17c90 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
17ca0 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
17cb0 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
17cc0 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
17cd0 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
17ce0 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
17cf0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
17d00 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
17d10 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
17d20 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
17d30 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
17d40 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
17d50 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
17d60 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
17d70 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
17d80 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
17d90 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
17da0 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
17db0 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
17dc0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
17dd0 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
17de0 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
17df0 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
17e00 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
17e10 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
17e20 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
17e30 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
17e40 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
17e50 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
17e60 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
17e70 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
17e80 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
17e90 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
17ea0 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
17eb0 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
17ec0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
17ed0 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
17ee0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
17ef0 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
17f00 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
17f10 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
17f20 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63  BUSY] error is c
17f30 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c  onverted to [SQL
17f40 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
17f50 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  D].** when SQLit
17f60 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64  e is in the midd
17f70 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72  le of a large tr
17f80 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20  ansaction where 
17f90 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67  all the.** chang
17fa0 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20  es will not fit 
17fb0 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  into the in-memo
17fc0 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74  ry cache.  SQLit
17fd0 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64  e will.** alread
17fe0 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45  y hold a RESERVE
17ff0 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61  D lock on the da
18000 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74  tabase file, but
18010 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20   it needs.** to 
18020 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63  promote this loc
18030 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73  k to EXCLUSIVE s
18040 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70  o that it can sp
18050 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67  ill cache.** pag
18060 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  es into the data
18070 62 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75  base file withou
18080 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72  t harm to concur
18090 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e  rent.** readers.
180a0 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62    ^If it is unab
180b0 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68  le to promote th
180c0 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65  e lock, then the
180d0 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61   in-memory.** ca
180e0 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74  che will be left
180f0 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74   in an inconsist
18100 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f  ent state and so
18110 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f   the error.** co
18120 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66  de is promoted f
18130 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65  rom the relative
18140 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54  ly benign [SQLIT
18150 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68  E_BUSY] to.** th
18160 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53  e more severe [S
18170 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
18180 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72  KED].  ^This err
18190 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f  or code promotio
181a0 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61  n.** forces an a
181b0 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63  utomatic rollbac
181c0 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73  k of the changes
181d0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61  .  See the.** <a
181e0 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f   href="/cvstrac/
181f0 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f  wiki?p=Corruptio
18200 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72  nFollowingBusyEr
18210 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74  ror">.** Corrupt
18220 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
18230 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70  Error</a> wiki p
18240 61 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73  age for a discus
18250 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74  sion of why.** t
18260 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74  his is important
18270 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
18280 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
18290 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
182a0 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61  r defined for ea
182b0 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ch.** [database 
182c0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65  connection].  Se
182d0 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79  tting a new busy
182e0 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20   handler clears 
182f0 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  any.** previousl
18300 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e  y set handler.)^
18310 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c    ^Note that cal
18320 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  ling [sqlite3_bu
18330 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a  sy_timeout()].**
18340 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f   will also set o
18350 72 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79  r clear the busy
18360 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
18370 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
18380 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
18390 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
183a0 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
183b0 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
183c0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
183d0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
183e0 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61  ler.  Any such a
183f0 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74  ctions.** result
18400 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
18410 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41  havior..** .** A
18420 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75   busy handler mu
18430 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65  st not close the
18440 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
18450 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70  tion.** or [prep
18460 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
18470 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
18480 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
18490 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
184a0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
184b0 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
184c0 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
184d0 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
184e0 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
184f0 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
18500 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
18510 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
18520 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
18530 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
18540 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
18550 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
18560 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
18570 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
18580 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
18590 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
185a0 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
185b0 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
185c0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
185d0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
185e0 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
185f0 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
18600 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
18610 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
18620 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
18630 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
18640 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
18650 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
18660 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
18670 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
18680 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
18690 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
186a0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
186b0 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
186c0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
186d0 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
186e0 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
186f0 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
18700 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
18710 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
18720 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
18730 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
18740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
18750 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20  ] any any given 
18760 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
18770 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
18780 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
18790 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
187a0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
187b0 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
187c0 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
187d0 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
187e0 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
187f0 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c  leared.)^.*/.SQL
18800 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
18810 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74  te3_busy_timeout
18820 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d  (sqlite3*, int m
18830 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  s);../*.** CAPI3
18840 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65  REF: Convenience
18850 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75   Routines For Ru
18860 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a  nning Queries.**
18870 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65  .** This is a le
18880 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74  gacy interface t
18890 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64  hat is preserved
188a0 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63   for backwards c
188b0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
188c0 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74   Use of this int
188d0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
188e0 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a  commended..**.**
188f0 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c   Definition: A <
18900 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f  b>result table</
18910 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74  b> is memory dat
18920 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61  a structure crea
18930 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73  ted by the.** [s
18940 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
18950 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
18960 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72  A result table r
18970 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f  ecords the.** co
18980 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73  mplete query res
18990 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72  ults from one or
189a0 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a   more queries..*
189b0 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63  *.** The table c
189c0 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20  onceptually has 
189d0 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73  a number of rows
189e0 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42   and columns.  B
189f0 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62  ut.** these numb
18a00 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74  ers are not part
18a10 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
18a20 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68  able itself.  Th
18a30 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61  ese.** numbers a
18a40 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61  re obtained sepa
18a50 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62  rately.  Let N b
18a60 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
18a70 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65  rows.** and M be
18a80 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
18a90 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20  olumns..**.** A 
18aa0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20  result table is 
18ab0 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
18ac0 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72  ters to zero-ter
18ad0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
18ae0 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20  rings..** There 
18af0 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d  are (N+1)*M elem
18b00 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61  ents in the arra
18b10 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20  y.  The first M 
18b20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a  pointers point.*
18b30 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  * to zero-termin
18b40 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61  ated strings tha
18b50 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e  t  contain the n
18b60 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75  ames of the colu
18b70 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61  mns..** The rema
18b80 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c  ining entries al
18b90 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79  l point to query
18ba0 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20   results.  NULL 
18bb0 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a  values result.**
18bc0 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72   in NULL pointer
18bd0 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  s.  All other va
18be0 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69  lues are in thei
18bf0 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72  r UTF-8 zero-ter
18c00 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
18c10 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  g representation
18c20 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20   as returned by 
18c30 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
18c40 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41  text()]..**.** A
18c50 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69   result table mi
18c60 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f  ght consist of o
18c70 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72  ne or more memor
18c80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a  y allocations..*
18c90 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
18ca0 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c   to pass a resul
18cb0 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79  t table directly
18cc0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
18cd0 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c  e()]..** A resul
18ce0 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62  t table should b
18cf0 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73  e deallocated us
18d00 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
18d10 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a  e_table()]..**.*
18d20 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c  * ^(As an exampl
18d30 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  e of the result 
18d40 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75  table format, su
18d50 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65  ppose a query re
18d60 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f  sult.** is as fo
18d70 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
18d80 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
18d90 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20  *        Name   
18da0 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20       | Age.**   
18db0 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d       -----------
18dc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20  ------------.** 
18dd0 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20         Alice    
18de0 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20     | 43.**      
18df0 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20    Bob         | 
18e00 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e  28.**        Cin
18e10 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a  dy       | 21.**
18e20 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
18e30 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65  ote>.**.** There
18e40 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20   are two column 
18e50 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65  (M==2) and three
18e60 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54   rows (N==3).  T
18e70 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  hus the.** resul
18e80 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e  t table has 8 en
18e90 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20  tries.  Suppose 
18ea0 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
18eb0 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e   is stored.** in
18ec0 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20   an array names 
18ed0 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20  azResult.  Then 
18ee0 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74  azResult holds t
18ef0 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a  his content:.**.
18f00 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
18f10 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61  pre>.**        a
18f20 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d  zResult&#91;0] =
18f30 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20   "Name";.**     
18f40 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
18f50 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20  1] = "Age";.**  
18f60 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
18f70 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b  91;2] = "Alice";
18f80 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
18f90 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33  ult&#91;3] = "43
18fa0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
18fb0 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22  esult&#91;4] = "
18fc0 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  Bob";.**        
18fd0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20  azResult&#91;5] 
18fe0 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20  = "28";.**      
18ff0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36    azResult&#91;6
19000 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20  ] = "Cindy";.** 
19010 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
19020 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a  #91;7] = "21";.*
19030 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
19040 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  uote>)^.**.** ^T
19050 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
19060 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  able() function 
19070 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72  evaluates one or
19080 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c   more.** semicol
19090 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c  on-separated SQL
190a0 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
190b0 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
190c0 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69  ed UTF-8.** stri
190d0 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61  ng of its 2nd pa
190e0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
190f0 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  rns a result tab
19100 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69  le to the.** poi
19110 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74  nter given in it
19120 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e  s 3rd parameter.
19130 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65  .**.** After the
19140 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73   application has
19150 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74   finished with t
19160 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73  he result from s
19170 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
19180 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70  (),.** it must p
19190 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74  ass the result t
191a0 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20  able pointer to 
191b0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
191c0 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f  le() in order to
191d0 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20  .** release the 
191e0 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20  memory that was 
191f0 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75  malloced.  Becau
19200 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68  se of the way th
19210 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61  e.** [sqlite3_ma
19220 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20  lloc()] happens 
19230 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67  within sqlite3_g
19240 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20  et_table(), the 
19250 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  calling.** funct
19260 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79  ion must not try
19270 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65   to call [sqlite
19280 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74  3_free()] direct
19290 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71  ly.  Only.** [sq
192a0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
192b0 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72  ()] is able to r
192c0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
192d0 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73  y properly and s
192e0 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  afely..**.** The
192f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
19300 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  le() interface i
19310 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73  s implemented as
19320 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e   a wrapper aroun
19330 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  d.** [sqlite3_ex
19340 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69  ec()].  The sqli
19350 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
19360 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74  routine does not
19370 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20   have access.** 
19380 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20  to any internal 
19390 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20  data structures 
193a0 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75  of SQLite.  It u
193b0 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62  ses only the pub
193c0 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  lic.** interface
193d0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20   defined here.  
193e0 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65  As a consequence
193f0 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63  , errors that oc
19400 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72  cur in the.** wr
19410 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73  apper layer outs
19420 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72  ide of the inter
19430 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  nal [sqlite3_exe
19440 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f  c()] call are no
19450 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69  t.** reflected i
19460 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
19470 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
19480 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20  rrcode()] or.** 
19490 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
194a0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
194b0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65  I int sqlite3_ge
194c0 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74  t_table(.  sqlit
194d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
194e0 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61   /* An open data
194f0 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
19500 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
19510 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
19520 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72  luated */.  char
19530 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20   ***pazResult,  
19540 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20    /* Results of 
19550 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69  the query */.  i
19560 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20  nt *pnRow,      
19570 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
19580 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72  f result rows wr
19590 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20  itten here */.  
195a0 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20  int *pnColumn,  
195b0 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20        /* Number 
195c0 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  of result column
195d0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
195e0 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72  /.  char **pzErr
195f0 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72  msg       /* Err
19600 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68  or msg written h
19610 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  ere */.);.SQLITE
19620 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
19630 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
19640 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
19650 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
19660 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
19670 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
19680 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
19690 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
196a0 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
196b0 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
196c0 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
196d0 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
196e0 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  d C library..**.
196f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
19700 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
19710 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
19720 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
19730 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
19740 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
19750 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
19760 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
19770 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
19780 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
19790 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
197a0 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
197b0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
197c0 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
197d0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
197e0 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
197f0 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
19800 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
19810 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
19820 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
19830 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
19840 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
19850 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
19860 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
19870 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
19880 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
19890 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
198a0 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
198b0 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
198c0 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
198d0 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
198e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
198f0 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
19900 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
19910 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
19920 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
19930 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
19940 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
19950 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
19960 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
19970 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
19980 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
19990 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
199a0 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
199b0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
199c0 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
199d0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
199e0 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
199f0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
19a00 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
19a10 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
19a20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
19a30 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
19a40 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
19a50 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
19a60 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
19a70 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
19a80 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
19a90 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
19aa0 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
19ab0 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
19ac0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
19ad0 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
19ae0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
19af0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
19b00 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
19b10 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
19b20 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
19b30 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
19b40 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
19b50 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
19b60 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
19b70 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
19b80 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
19b90 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
19ba0 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
19bb0 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
19bc0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
19bd0 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
19be0 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
19bf0 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
19c00 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
19c10 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
19c20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
19c30 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
19c40 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
19c50 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
19c60 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
19c70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
19c80 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
19c90 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
19ca0 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
19cb0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
19cc0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
19cd0 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
19ce0 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
19cf0 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
19d00 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
19d10 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
19d20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
19d30 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
19d40 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
19d50 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
19d60 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
19d70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
19d80 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
19d90 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
19da0 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
19db0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
19dc0 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
19dd0 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
19de0 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
19df0 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
19e00 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
19e10 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
19e20 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
19e30 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
19e40 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
19e50 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
19e60 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
19e70 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
19e80 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
19e90 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
19ea0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
19eb0 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
19ec0 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
19ed0 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
19ee0 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
19ef0 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
19f00 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
19f10 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
19f20 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
19f30 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
19f40 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
19f50 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
19f60 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
19f70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
19f80 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
19f90 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
19fa0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
19fb0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
19fc0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
19fd0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
19fe0 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
19ff0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1a000 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1a010 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1a020 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
1a030 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1a040 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1a050 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1a060 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1a070 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1a080 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
1a090 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
1a0a0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
1a0b0 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
1a0c0 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
1a0d0 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
1a0e0 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
1a0f0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1a100 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1a110 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1a120 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1a130 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
1a140 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
1a150 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1a160 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
1a170 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
1a180 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
1a190 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
1a1a0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
1a1b0 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
1a1c0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1a1d0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1a1e0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1a1f0 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1a200 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
1a210 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
1a220 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1a230 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
1a240 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
1a250 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
1a260 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
1a270 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
1a280 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
1a290 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
1a2a0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
1a2b0 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
1a2c0 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
1a2d0 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
1a2e0 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
1a2f0 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
1a300 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
1a310 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
1a320 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
1a330 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
1a340 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
1a350 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
1a360 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
1a370 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1a380 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
1a390 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
1a3a0 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
1a3b0 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
1a3c0 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
1a3d0 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
1a3e0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1a3f0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1a400 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1a410 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1a420 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1a430 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
1a440 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1a450 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1a460 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1a470 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1a480 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1a490 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
1a4a0 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
1a4b0 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
1a4c0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1a4d0 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
1a4e0 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
1a4f0 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
1a500 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
1a510 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
1a520 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1a530 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1a540 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1a550 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1a560 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1a570 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1a580 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1a590 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1a5a0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1a5b0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1a5c0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1a5d0 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ng.)^.*/.SQLITE_
1a5e0 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
1a5f0 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  3_mprintf(const 
1a600 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49  char*,...);.SQLI
1a610 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
1a620 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f  ite3_vmprintf(co
1a630 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1a640 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  st);.SQLITE_API 
1a650 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e  char *sqlite3_sn
1a660 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1a670 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e  ,const char*, ..
1a680 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .);.SQLITE_API c
1a690 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e  har *sqlite3_vsn
1a6a0 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
1a6b0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
1a6c0 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
1a6d0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1a6e0 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
1a6f0 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
1a700 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
1a710 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
1a720 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
1a730 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
1a740 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
1a750 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
1a760 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
1a770 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
1a780 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1a790 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
1a7a0 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
1a7b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
1a7c0 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
1a7d0 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
1a7e0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1a7f0 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
1a800 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
1a810 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
1a820 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
1a830 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1a840 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
1a850 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
1a860 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
1a870 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1a880 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
1a890 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
1a8a0 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
1a8b0 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
1a8c0 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
1a8d0 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
1a8e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
1a8f0 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
1a900 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
1a910 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
1a920 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
1a930 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
1a940 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
1a950 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
1a960 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
1a970 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
1a980 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
1a990 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
1a9a0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
1a9b0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1a9c0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
1a9d0 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
1a9e0 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
1a9f0 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
1aa00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
1aa10 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
1aa20 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
1aa30 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
1aa40 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
1aa50 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
1aa60 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
1aa70 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
1aa80 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
1aa90 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
1aaa0 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
1aab0 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
1aac0 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
1aad0 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
1aae0 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
1aaf0 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
1ab00 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
1ab10 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
1ab20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
1ab30 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
1ab40 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
1ab50 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
1ab60 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
1ab70 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
1ab80 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
1ab90 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
1aba0 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
1abb0 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
1abc0 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
1abd0 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
1abe0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
1abf0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
1ac00 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  (The sqlite3_rea
1ac10 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
1ac20 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
1ac30 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
1ac40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ac50 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
1ac60 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
1ac70 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
1ac80 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
1ac90 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
1aca0 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
1acb0 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
1acc0 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e  * parameter.)^ ^
1acd0 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
1ace0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1acf0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
1ad00 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1ad10 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
1ad20 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
1ad30 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
1ad40 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
1ad50 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1ad60 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1ad70 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1ad80 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  loc()..** ^If th
1ad90 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1ada0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1adb0 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
1adc0 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
1add0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
1ade0 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
1adf0 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
1ae00 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
1ae10 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68  P) where P is th
1ae20 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1ae30 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1ae40 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69  lloc()..** ^sqli
1ae50 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1ae60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1ae70 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
1ae80 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
1ae90 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
1aea0 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
1aeb0 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
1aec0 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  ry is unavailabl
1aed0 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74  e..** ^If M is t
1aee0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
1aef0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
1af00 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
1af10 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
1af20 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
1af30 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
1af40 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
1af50 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
1af60 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
1af70 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65  ealloc() and the
1af80 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1af90 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
1afa0 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
1afb0 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  oc() returns NUL
1afc0 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f  L, then the prio
1afd0 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  r allocation.** 
1afe0 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
1aff0 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
1b000 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
1b010 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  te3_malloc() and
1b020 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1b030 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
1b040 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
1b050 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
1b060 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a  undary, or to a.
1b070 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61  ** 4 byte bounda
1b080 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ry if the [SQLIT
1b090 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44  E_4_BYTE_ALIGNED
1b0a0 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65  _MALLOC] compile
1b0b0 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
1b0c0 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
1b0d0 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
1b0e0 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
1b0f0 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
1b100 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
1b110 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
1b120 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
1b130 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
1b140 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
1b150 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
1b160 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
1b170 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
1b180 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
1b190 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
1b1a0 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
1b1b0 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
1b1c0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
1b1d0 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
1b1e0 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74  * Prior to SQLit
1b1f0 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30  e version 3.7.10
1b200 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  , the Windows OS
1b210 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
1b220 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73   called.** the s
1b230 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61  ystem malloc() a
1b240 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74  nd free() direct
1b250 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69  ly when converti
1b260 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20  ng.** filenames 
1b270 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d  between the UTF-
1b280 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  8 encoding used 
1b290 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64  by SQLite.** and
1b2a0 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61   whatever filena
1b2b0 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  me encoding is u
1b2c0 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69  sed by the parti
1b2d0 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a  cular Windows.**
1b2e0 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20   installation.  
1b2f0 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
1b300 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65  n errors were de
1b310 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
1b320 68 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65  hey were reporte
1b330 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54  d back as [SQLIT
1b340 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a  E_CANTOPEN] or.*
1b350 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d  * [SQLITE_IOERR]
1b360 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51   rather than [SQ
1b370 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a  LITE_NOMEM]..**.
1b380 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61  ** The pointer a
1b390 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c  rguments to [sql
1b3a0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64  ite3_free()] and
1b3b0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1b3c0 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  c()].** must be 
1b3d0 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65  either NULL or e
1b3e0 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74  lse pointers obt
1b3f0 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69  ained from a pri
1b400 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  or.** invocation
1b410 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   of [sqlite3_mal
1b420 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  loc()] or [sqlit
1b430 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68  e3_realloc()] th
1b440 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79  at have.** not y
1b450 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  et been released
1b460 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
1b470 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74  ication must not
1b480 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61   read or write a
1b490 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20  ny part of.** a 
1b4a0 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20  block of memory 
1b4b0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
1b4c0 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67  n released using
1b4d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  .** [sqlite3_fre
1b4e0 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  e()] or [sqlite3
1b4f0 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a  _realloc()]..*/.
1b500 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1b510 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  *sqlite3_malloc(
1b520 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
1b530 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72   void *sqlite3_r
1b540 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
1b550 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
1b560 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
1b570 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
1b580 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
1b590 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
1b5a0 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
1b5b0 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
1b5c0 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
1b5d0 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
1b5e0 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
1b5f0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
1b600 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
1b610 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
1b620 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1b630 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
1b640 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
1b650 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1b660 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
1b670 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
1b680 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1b690 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
1b6a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
1b6b0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
1b6c0 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
1b6d0 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
1b6e0 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
1b6f0 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
1b700 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
1b710 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
1b720 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1b730 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
1b740 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
1b750 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1b760 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
1b770 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
1b780 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
1b790 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
1b7a0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
1b7b0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
1b7c0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
1b7d0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1b7e0 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
1b7f0 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
1b800 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
1b810 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
1b820 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1b830 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
1b840 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
1b850 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
1b860 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
1b870 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
1b880 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
1b890 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
1b8a0 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
1b8b0 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
1b8c0 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
1b8d0 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
1b8e0 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
1b8f0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1b900 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
1b910 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
1b920 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
1b930 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1b940 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
1b950 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
1b960 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
1b970 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1b980 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
1b990 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
1b9a0 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
1b9b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1b9c0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
1b9d0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1b9e0 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  d(void);.SQLITE_
1b9f0 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
1ba00 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1ba10 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1ba20 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1ba30 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1ba40 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1ba50 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1ba60 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1ba70 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1ba80 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1ba90 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1baa0 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1bab0 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1bac0 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1bad0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1bae0 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1baf0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1bb00 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1bb10 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1bb20 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1bb30 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1bb40 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1bb50 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1bb60 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1bb70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1bb80 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1bb90 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1bba0 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1bbb0 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1bbc0 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1bbd0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1bbe0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1bbf0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1bc00 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1bc10 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  o buffer P..**.*
1bc20 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
1bc30 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
1bc40 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
1bc50 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
1bc60 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
1bc70 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
1bc80 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
1bc90 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
1bca0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
1bcb0 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
1bcc0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
1bcd0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1bce0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61  object..** ^On a
1bcf0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
1bd00 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70  vocations, the p
1bd10 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
1bd20 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
1bd30 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
1bd40 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
1bd50 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1bd60 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
1bd70 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  s.** method..*/.
1bd80 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
1bd90 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65  sqlite3_randomne
1bda0 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a  ss(int N, void *
1bdb0 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  P);../*.** CAPI3
1bdc0 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d  REF: Compile-Tim
1bdd0 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  e Authorization 
1bde0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
1bdf0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65  ^This routine re
1be00 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f  gisters an autho
1be10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77  rizer callback w
1be20 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72  ith a particular
1be30 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1be40 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c  nnection], suppl
1be50 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
1be60 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
1be70 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1be80 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1be90 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65  d as SQL stateme
1bea0 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f  nts are being co
1beb0 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71  mpiled.** by [sq
1bec0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
1bed0 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
1bee0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1bef0 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  e_v2()],.** [sql
1bf00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
1bf10 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
1bf20 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20  repare16_v2()]. 
1bf30 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20   ^At various.** 
1bf40 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68  points during th
1bf50 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72  e compilation pr
1bf60 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20  ocess, as logic 
1bf70 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  is being created
1bf80 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76  .** to perform v
1bf90 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20  arious actions, 
1bfa0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1bfb0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1bfc0 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20  ed to.** see if 
1bfd0 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72  those actions ar
1bfe0 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65  e allowed.  ^The
1bff0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1c000 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  back should.** r
1c010 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
1c020 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61  ] to allow the a
1c030 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49  ction, [SQLITE_I
1c040 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c  GNORE] to disall
1c050 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66  ow the.** specif
1c060 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c  ic action but al
1c070 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74  low the SQL stat
1c080 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75  ement to continu
1c090 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69  e to be.** compi
1c0a0 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  led, or [SQLITE_
1c0b0 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74  DENY] to cause t
1c0c0 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74  he entire SQL st
1c0d0 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a  atement to be.**
1c0e0 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61   rejected with a
1c0f0 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68  n error.  ^If th
1c100 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1c110 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a  lback returns.**
1c120 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72   any value other
1c130 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47   than [SQLITE_IG
1c140 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  NORE], [SQLITE_O
1c150 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  K], or [SQLITE_D
1c160 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ENY].** then the
1c170 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c180 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1c190 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1c1a0 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65  triggered.** the
1c1b0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1c1c0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1c1d0 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a  ror message..**.
1c1e0 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c  ** When the call
1c1f0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1c200 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d  LITE_OK], that m
1c210 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69  eans the operati
1c220 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  on.** requested 
1c230 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68  is ok.  ^When th
1c240 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1c250 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  ns [SQLITE_DENY]
1c260 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  , the.** [sqlite
1c270 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1c280 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1c290 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1c2a0 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69  d the.** authori
1c2b0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1c2c0 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1c2d0 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74  age explaining t
1c2e0 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73  hat.** access is
1c2f0 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20   denied. .**.** 
1c300 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
1c310 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1c320 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1c330 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1c340 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65   third.** parame
1c350 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
1c360 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1c370 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e  r() interface. ^
1c380 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
1c390 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63  eter.** to the c
1c3a0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1c3b0 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f  teger [SQLITE_CO
1c3c0 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65  PY | action code
1c3d0 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  ] that specifies
1c3e0 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c  .** the particul
1c3f0 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20  ar action to be 
1c400 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65  authorized. ^The
1c410 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73   third through s
1c420 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a  ixth parameters.
1c430 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1c440 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d  ck are zero-term
1c450 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1c460 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69  hat contain addi
1c470 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c  tional.** detail
1c480 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69  s about the acti
1c490 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
1c4a0 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  zed..**.** ^If t
1c4b0 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69  he action code i
1c4c0 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a  s [SQLITE_READ].
1c4d0 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  ** and the callb
1c4e0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1c4f0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1c500 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
1c510 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61  d statement] sta
1c520 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72  tement is constr
1c530 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74  ucted to substit
1c540 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61  ute.** a NULL va
1c550 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  lue in place of 
1c560 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  the table column
1c570 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65   that would have
1c580 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66  .** been read if
1c590 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64   [SQLITE_OK] had
1c5a0 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20   been returned. 
1c5b0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e   The [SQLITE_IGN
1c5c0 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63  ORE].** return c
1c5d0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65  an be used to de
1c5e0 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  ny an untrusted 
1c5f0 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69  user access to i
1c600 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c  ndividual.** col
1c610 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e  umns of a table.
1c620 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
1c630 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
1c640 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74  TE_DELETE] and t
1c650 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1c660 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  rns.** [SQLITE_I
1c670 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20  GNORE] then the 
1c680 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69  [DELETE] operati
1c690 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20  on proceeds but 
1c6a0 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65  the.** [truncate
1c6b0 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69   optimization] i
1c6c0 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61  s disabled and a
1c6d0 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  ll rows are dele
1c6e0 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79  ted individually
1c6f0 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f  ..**.** An autho
1c700 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68  rizer is used wh
1c710 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
1c720 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d  are | preparing]
1c730 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1c740 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75  ts from an untru
1c750 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20  sted source, to 
1c760 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
1c770 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1c780 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20  * do not try to 
1c790 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79  access data they
1c7a0 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64   are not allowed
1c7b0 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74   to see, or that
1c7c0 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20   they do not.** 
1c7d0 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d  try to execute m
1c7e0 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65  alicious stateme
1c7f0 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20  nts that damage 
1c800 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46  the database.  F
1c810 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61  or.** example, a
1c820 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61  n application ma
1c830 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74  y allow a user t
1c840 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72  o enter arbitrar
1c850 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73  y.** SQL queries
1c860 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20   for evaluation 
1c870 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20  by a database.  
1c880 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74  But the applicat
1c890 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ion does.** not 
1c8a0 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f  want the user to
1c8b0 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65   be able to make
1c8c0 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67   arbitrary chang
1c8d0 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74  es to the.** dat
1c8e0 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f  abase.  An autho
1c8f0 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e  rizer could then
1c900 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65   be put in place
1c910 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73   while the.** us
1c920 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69  er-entered SQL i
1c930 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33  s being [sqlite3
1c940 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1c950 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73  red] that.** dis
1c960 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e  allows everythin
1c970 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54  g except [SELECT
1c980 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
1c990 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
1c9a0 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72   that need to pr
1c9b0 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75  ocess SQL from u
1c9c0 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73  ntrusted sources
1c9d0 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63  .** might also c
1c9e0 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67  onsider lowering
1c9f0 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73   resource limits
1ca00 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1ca10 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20  limit()].** and 
1ca20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73  limiting databas
1ca30 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65  e size using the
1ca40 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1ca50 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e  ] [PRAGMA].** in
1ca60 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69   addition to usi
1ca70 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  ng an authorizer
1ca80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61  ..**.** ^(Only a
1ca90 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a   single authoriz
1caa0 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61  er can be in pla
1cab0 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65  ce on a database
1cac0 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61   connection.** a
1cad0 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20  t a time.  Each 
1cae0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
1caf0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f  set_authorizer o
1cb00 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20  verrides the.** 
1cb10 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e  previous call.)^
1cb20 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61    ^Disable the a
1cb30 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73  uthorizer by ins
1cb40 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63  talling a NULL c
1cb50 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20  allback..** The 
1cb60 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69  authorizer is di
1cb70 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
1cb80 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74  t..**.** The aut
1cb90 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1cba0 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
1cbb0 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
1cbc0 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
1cbd0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1cbe0 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
1cbf0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1cc00 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  llback..** Note 
1cc10 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1cc20 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1cc30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1cc40 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1cc50 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1cc60 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1cc70 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1cc80 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1cc90 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
1cca0 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ^When [sqlite3_p
1ccb0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20  repare_v2()] is 
1ccc0 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20  used to prepare 
1ccd0 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65  a statement, the
1cce0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69  .** statement mi
1ccf0 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72  ght be re-prepar
1cd00 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74  ed during [sqlit
1cd10 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74  e3_step()] due t
1cd20 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63  o a .** schema c
1cd30 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74  hange.  Hence, t
1cd40 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
1cd50 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61  hould ensure tha
1cd60 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74  t the.** correct
1cd70 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1cd80 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20  back remains in 
1cd90 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65  place during the
1cda0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1cdb0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74  ]..**.** ^Note t
1cdc0 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a  hat the authoriz
1cdd0 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1cde0 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69  nvoked only duri
1cdf0 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ng.** [sqlite3_p
1ce00 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1ce10 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68   variants.  Auth
1ce20 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74  orization is not
1ce30 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75  .** performed du
1ce40 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65  ring statement e
1ce50 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71  valuation in [sq
1ce60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75  lite3_step()], u
1ce70 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74  nless.** as stat
1ce80 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  ed in the previo
1ce90 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71  us paragraph, sq
1cea0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76  lite3_step() inv
1ceb0 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  okes.** sqlite3_
1cec0 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20  prepare_v2() to 
1ced0 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74  reprepare a stat
1cee0 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63  ement after a sc
1cef0 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a  hema change..*/.
1cf00 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1cf10 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1cf20 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
1cf30 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
1cf40 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
1cf50 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1cf60 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1cf70 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
1cf80 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
1cf90 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1cfa0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
1cfb0 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
1cfc0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1cfd0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1cfe0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1cff0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
1d000 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
1d010 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
1d020 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
1d030 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
1d040 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
1d050 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
1d060 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
1d070 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
1d080 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
1d090 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1d0a0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1d0b0 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
1d0c0 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
1d0d0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
1d0e0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
1d0f0 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
1d100 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
1d110 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41  a [SQLITE_ROLLBA
1d120 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65  CK | return code
1d130 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73  ].** from the [s
1d140 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63  qlite3_vtab_on_c
1d150 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72  onflict()] inter
1d160 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  face..*/.#define
1d170 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
1d180 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
1d190 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
1d1a0 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
1d1b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
1d1c0 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
1d1d0 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
1d1e0 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
1d1f0 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
1d200 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d210 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
1d220 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
1d230 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1d240 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
1d250 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
1d260 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1d270 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
1d280 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
1d290 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c  rize certain SQL
1d2a0 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
1d2b0 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
1d2c0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1d2d0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1d2e0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
1d2f0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
1d300 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
1d310 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
1d320 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
1d330 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
1d340 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
1d350 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1d360 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
1d370 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
1d380 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
1d390 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
1d3a0 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
1d3b0 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20  ion is to be.** 
1d3c0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1d3d0 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
1d3e0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61  ameters to the a
1d3f0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20  uthorization.** 
1d400 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1d410 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65  n will be parame
1d420 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
1d430 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
1d440 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65  of these.** code
1d450 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  s is used as the
1d460 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1d470 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61  r.  ^(The 5th pa
1d480 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
1d490 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
1d4a0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
1d4b0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1d4c0 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
1d4d0 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
1d4e0 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54  pplicable.)^  ^T
1d4f0 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
1d500 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1d510 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
1d520 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1d530 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
1d540 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
1d550 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
1d560 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
1d570 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
1d580 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
1d590 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
1d5a0 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
1d5b0 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
1d5c0 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
1d5d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d5e0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1d5f0 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
1d600 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
1d610 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
1d620 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
1d630 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
1d640 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1d650 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1d660 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d670 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
1d680 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
1d690 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1d6a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1d6b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d6c0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
1d6d0 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
1d6e0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1d6f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1d700 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d710 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
1d720 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
1d730 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1d740 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1d750 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1d760 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
1d770 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
1d780 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1d790 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1d7a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1d7b0 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
1d7c0 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
1d7d0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1d7e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1d7f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1d800 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
1d810 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
1d820 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1d830 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1d840 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1d850 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
1d860 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
1d870 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1d880 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1d890 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
1d8a0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1d8b0 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
1d8c0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1d8d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1d8e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
1d8f0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
1d900 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
1d910 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1d920 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1d930 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
1d940 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
1d950 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1d960 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1d970 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1d980 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1d990 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
1d9a0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1d9b0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1d9c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1d9d0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1d9e0 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
1d9f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1da00 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1da10 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1da20 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1da30 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
1da40 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1da50 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1da60 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1da70 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
1da80 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
1da90 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1daa0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1dab0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1dac0 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
1dad0 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
1dae0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1daf0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1db00 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1db10 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
1db20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
1db30 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1db40 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1db50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1db60 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
1db70 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
1db80 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1db90 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1dba0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1dbb0 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
1dbc0 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
1dbd0 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
1dbe0 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
1dbf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1dc00 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
1dc10 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
1dc20 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1dc30 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1dc40 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1dc50 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1dc60 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
1dc70 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
1dc80 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1dc90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
1dca0 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
1dcb0 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61     22   /* Opera
1dcc0 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20  tion       NULL 
1dcd0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1dce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
1dcf0 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
1dd00 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
1dd10 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1dd20 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1dd30 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
1dd40 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
1dd50 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
1dd60 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
1dd70 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1dd80 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
1dd90 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1dda0 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
1ddb0 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
1ddc0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1ddd0 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
1dde0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1ddf0 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
1de00 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
1de10 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1de20 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
1de30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
1de40 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1de50 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1de60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1de70 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
1de80 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
1de90 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1dea0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1deb0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1dec0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
1ded0 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
1dee0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1def0 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1df00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1df10 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
1df20 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
1df30 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1df40 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
1df50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1df60 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
1df70 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
1df80 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1df90 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20    Function Name 
1dfa0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1dfb0 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20  ITE_SAVEPOINT   
1dfc0 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a           32   /*
1dfd0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1dfe0 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20   Savepoint Name 
1dff0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1e000 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
1e010 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
1e020 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
1e030 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1e040 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
1e050 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
1e060 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1e070 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
1e080 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1e090 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
1e0a0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
1e0b0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
1e0c0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
1e0d0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1e0e0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
1e0f0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1e100 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1e110 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
1e120 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
1e130 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
1e140 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1e150 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
1e160 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
1e170 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
1e180 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
1e190 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1e1a0 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
1e1b0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
1e1c0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
1e1d0 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
1e1e0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
1e1f0 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
1e200 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
1e210 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
1e220 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
1e230 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
1e240 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
1e250 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
1e260 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
1e270 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
1e280 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
1e290 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
1e2a0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
1e2b0 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
1e2c0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1e2d0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1e2e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
1e2f0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
1e300 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
1e310 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
1e320 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
1e330 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
1e340 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
1e350 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
1e360 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
1e370 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
1e380 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
1e390 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
1e3a0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
1e3b0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1e3c0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
1e3d0 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
1e3e0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
1e3f0 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
1e400 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
1e410 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
1e420 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
1e430 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
1e440 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
1e450 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
1e460 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
1e470 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
1e480 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1e490 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
1e4a0 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
1e4b0 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
1e4c0 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
1e4d0 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
1e4e0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
1e4f0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
1e500 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
1e510 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
1e520 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
1e530 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
1e540 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1e550 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1e560 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72  void *sqlite3_tr
1e570 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f  ace(sqlite3*, vo
1e580 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64  id(*xTrace)(void
1e590 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  *,const char*), 
1e5a0 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  void*);.SQLITE_A
1e5b0 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49  PI SQLITE_EXPERI
1e5c0 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c  MENTAL void *sql
1e5d0 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c  ite3_profile(sql
1e5e0 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a  ite3*,.   void(*
1e5f0 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c  xProfile)(void*,
1e600 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69  const char*,sqli
1e610 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69  te3_uint64), voi
1e620 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1e630 33 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67  3REF: Query Prog
1e640 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  ress Callbacks.*
1e650 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1e660 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
1e670 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65  er(D,N,X,P) inte
1e680 72 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65  rface causes the
1e690 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e   callback.** fun
1e6a0 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e  ction X to be in
1e6b0 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c  voked periodical
1e6c0 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72  ly during long r
1e6d0 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a  unning calls to.
1e6e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ** [sqlite3_exec
1e6f0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
1e700 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ep()] and [sqlit
1e710 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20  e3_get_table()] 
1e720 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  for.** database 
1e730 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41  connection D.  A
1e740 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f  n example use fo
1e750 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66  r this.** interf
1e760 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61  ace is to keep a
1e770 20 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72   GUI updated dur
1e780 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72  ing a large quer
1e790 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61  y..**.** ^The pa
1e7a0 72 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73  rameter P is pas
1e7b0 73 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74  sed through as t
1e7c0 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
1e7d0 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c  r to the .** cal
1e7e0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58  lback function X
1e7f0 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  .  ^The paramete
1e800 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65  r N is the numbe
1e810 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61  r of .** [virtua
1e820 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75  l machine instru
1e830 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65  ctions] that are
1e840 20 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65   evaluated betwe
1e850 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a  en successive.**
1e860 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
1e870 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a  the callback X..
1e880 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
1e890 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
1e8a0 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
1e8b0 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
1e8c0 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
1e8d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
1e8e0 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
1e8f0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
1e900 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
1e910 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
1e920 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
1e930 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
1e940 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1e950 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
1e960 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
1e970 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
1e980 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
1e990 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
1e9a0 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
1e9b0 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
1e9c0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
1e9d0 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
1e9e0 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
1e9f0 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
1ea00 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
1ea10 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
1ea20 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
1ea30 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
1ea40 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
1ea50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
1ea60 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
1ea70 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1ea80 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1ea90 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1eaa0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1eab0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1eac0 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
1ead0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
1eae0 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
1eaf0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
1eb00 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
1eb10 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
1eb20 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
1eb30 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
1eb40 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
1eb50 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
1eb60 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
1eb70 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1eb80 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
1eb90 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
1eba0 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
1ebb0 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
1ebc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1ebd0 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
1ebe0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
1ebf0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ion.**.** ^These
1ec00 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
1ec10 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
1ec20 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
1ec30 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
1ec40 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
1ec50 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
1ec60 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
1ec70 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
1ec80 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1ec90 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1eca0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
1ecb0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
1ecc0 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
1ecd0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
1ece0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
1ecf0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1ed00 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
1ed10 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
1ed20 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
1ed30 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
1ed40 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
1ed50 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
1ed60 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
1ed70 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
1ed80 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
1ed90 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
1eda0 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
1edb0 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
1edc0 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
1edd0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
1ede0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
1edf0 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
1ee00 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
1ee10 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1ee20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
1ee30 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
1ee40 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
1ee50 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
1ee60 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
1ee70 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
1ee80 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
1ee90 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1eea0 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
1eeb0 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
1eec0 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
1eed0 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
1eee0 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
1eef0 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
1ef00 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
1ef10 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
1ef20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
1ef30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1ef40 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
1ef50 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
1ef60 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
1ef70 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
1ef80 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
1ef90 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
1efa0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1efb0 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
1efc0 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
1efd0 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
1efe0 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
1eff0 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
1f000 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
1f010 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
1f020 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
1f030 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
1f040 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
1f050 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
1f060 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1f070 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
1f080 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
1f090 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
1f0a0 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
1f0b0 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
1f0c0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
1f0d0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
1f0e0 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
1f0f0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
1f100 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
1f110 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
1f120 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
1f130 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
1f140 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
1f150 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
1f160 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1f170 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
1f180 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
1f190 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
1f1a0 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
1f1b0 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
1f1c0 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
1f1d0 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
1f1e0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
1f1f0 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
1f200 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
1f210 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
1f220 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
1f230 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
1f240 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
1f250 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
1f260 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
1f270 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
1f280 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
1f290 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1f2a0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
1f2b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1f2c0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1f2d0 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
1f2e0 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
1f2f0 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1f300 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
1f310 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
1f320 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
1f330 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
1f340 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1f350 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1f360 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1f370 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1f380 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1f390 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
1f3a0 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
1f3b0 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
1f3c0 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1f3d0 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1f3e0 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
1f3f0 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
1f400 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
1f410 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
1f420 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
1f430 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1f440 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1f450 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1f460 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
1f470 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
1f480 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1f490 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1f4a0 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1f4b0 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
1f4c0 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
1f4d0 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
1f4e0 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
1f4f0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
1f500 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
1f510 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
1f520 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1f530 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
1f540 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
1f550 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1f560 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1f570 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1f580 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1f590 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1f5a0 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
1f5b0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
1f5c0 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
1f5d0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
1f5e0 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
1f5f0 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
1f600 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
1f610 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
1f620 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
1f630 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
1f640 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
1f650 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1f660 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
1f670 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
1f680 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
1f690 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
1f6a0 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
1f6b0 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
1f6c0 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
1f6d0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
1f6e0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
1f6f0 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
1f700 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
1f710 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
1f720 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1f730 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
1f740 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
1f750 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
1f760 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
1f770 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
1f780 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
1f790 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
1f7a0 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
1f7b0 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
1f7c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
1f7d0 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
1f7e0 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
1f7f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
1f800 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
1f810 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
1f820 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
1f830 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1f840 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
1f850 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
1f860 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1f870 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
1f880 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
1f890 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
1f8a0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
1f8b0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
1f8c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f8d0 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
1f8e0 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
1f8f0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
1f900 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
1f910 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
1f920 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
1f930 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
1f940 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
1f950 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
1f960 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1f970 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
1f980 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
1f990 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
1f9a0 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
1f9b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1f9c0 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
1f9d0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
1f9e0 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
1f9f0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
1fa00 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1fa10 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1fa20 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
1fa30 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
1fa40 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
1fa50 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1fa60 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
1fa70 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
1fa80 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
1fa90 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
1faa0 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
1fab0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
1fac0 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
1fad0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
1fae0 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
1faf0 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1fb00 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
1fb10 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
1fb20 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
1fb30 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
1fb40 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
1fb50 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
1fb60 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
1fb70 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
1fb80 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
1fb90 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
1fba0 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
1fbb0 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
1fbc0 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
1fbd0 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
1fbe0 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
1fbf0 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
1fc00 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
1fc10 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
1fc20 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
1fc30 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
1fc40 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
1fc50 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
1fc60 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
1fc70 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
1fc80 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
1fc90 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
1fca0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
1fcb0 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
1fcc0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1fcd0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1fce0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
1fcf0 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
1fd00 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
1fd10 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
1fd20 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
1fd30 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
1fd40 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
1fd50 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
1fd60 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
1fd70 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
1fd80 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
1fd90 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1fda0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
1fdb0 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
1fdc0 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
1fdd0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
1fde0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
1fdf0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
1fe00 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
1fe10 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
1fe20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1fe30 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
1fe40 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
1fe50 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
1fe60 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
1fe70 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
1fe80 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
1fe90 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
1fea0 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
1feb0 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
1fec0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1fed0 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20  ption..** As of 
1fee0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1fef0 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61  .7.7, URI filena
1ff00 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
1ff10 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a  n is turned off.
1ff20 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62  ** by default, b
1ff30 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ut future releas
1ff40 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  es of SQLite mig
1ff50 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69  ht enable URI fi
1ff60 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70  lename.** interp
1ff70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61  retation by defa
1ff80 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20  ult.  See "[URI 
1ff90 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20  filenames]" for 
1ffa0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
1ffb0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
1ffc0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61   URI filenames a
1ffd0 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64  re parsed accord
1ffe0 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e  ing to RFC 3986.
1fff0 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e   ^If the URI con
20000 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68  tains an.** auth
20010 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d  ority, then it m
20020 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e  ust be either an
20030 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
20040 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20   the string .** 
20050 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66  "localhost". ^If
20060 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69   the authority i
20070 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73  s not an empty s
20080 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68  tring or "localh
20090 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72  ost", an .** err
200a0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74  or is returned t
200b0 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54  o the caller. ^T
200c0 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70  he fragment comp
200d0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20  onent of a URI, 
200e0 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20  if .** present, 
200f0 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
20100 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
20110 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e  he path componen
20120 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20  t of the URI as 
20130 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
20140 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69  disk file.** whi
20150 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ch contains the 
20160 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68  database. ^If th
20170 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69  e path begins wi
20180 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74  th a '/' charact
20190 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20  er, .** then it 
201a0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
201b0 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  s an absolute pa
201c0 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  th. ^If the path
201d0 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20   does not begin 
201e0 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28  .** with a '/' (
201f0 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65  meaning that the
20200 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69   authority secti
20210 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  on is omitted fr
20220 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74  om the URI).** t
20230 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20  hen the path is 
20240 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
20250 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20   relative path. 
20260 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c  .** ^On windows,
20270 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
20280 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
20290 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
202a0 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
202b0 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
202c0 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )..**.** [[core 
202d0 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
202e0 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
202f0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
20300 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
20310 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
20320 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
20330 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
20340 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
20350 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
20360 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
20370 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
20380 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
20390 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
203a0 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ee query paramet
203b0 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
203c0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
203d0 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
203e0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
203f0 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
20400 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
20410 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
20420 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
20430 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
20440 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
20450 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
20460 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
20470 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
20480 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
20490 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
204a0 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
204b0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
204c0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
204d0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
204e0 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
204f0 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
20500 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
20510 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
20520 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
20530 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
20540 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
20550 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
20560 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
20570 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
20580 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
20590 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
205a0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
205b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
205c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
205d0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
205e0 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
205f0 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
20600 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
20610 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
20620 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22  w",.**     "rwc"
20630 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41  , or "memory". A
20640 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74  ttempting to set
20650 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72   it to any other
20660 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20   value is.**    
20670 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
20680 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
20690 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
206a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
206b0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
206c0 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
206d0 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
206e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
206f0 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
20700 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
20710 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
20720 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
20730 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
20740 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
20750 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
20760 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
20770 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
20780 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
20790 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
207a0 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
207b0 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
207c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
207d0 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
207e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
207f0 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
20800 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
20810 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
20820 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
20830 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
20840 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
20850 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
20860 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
20870 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
20880 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
20890 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
208a0 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
208b0 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
208c0 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
208d0 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
208e0 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
208f0 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
20900 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
20910 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
20920 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
20930 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
20940 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
20950 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
20960 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
20970 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
20980 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
20990 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
209a0 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
209b0 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
209c0 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
209d0 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
209e0 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
209f0 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
20a00 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
20a10 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
20a20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
20a30 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
20a40 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
20a50 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
20a60 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
20a70 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
20a80 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
20a90 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
20aa0 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
20ab0 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
20ac0 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
20ad0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
20ae0 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
20af0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
20b00 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
20b10 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
20b20 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
20b30 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
20b40 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
20b50 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
20b60 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
20b70 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
20b80 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72 65 71  ny behaviour req
20b90 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e  uested by settin
20ba0 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  g.**     SQLITE_
20bb0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
20bc0 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e  E or SQLITE_OPEN
20bd0 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61  _SHAREDCACHE fla
20be0 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  g..** </ul>.**.*
20bf0 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
20c00 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
20c10 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
20c20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
20c30 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
20c40 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
20c50 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
20c60 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
20c70 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
20c80 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
20c90 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
20ca0 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
20cb0 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
20cc0 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
20cd0 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
20ce0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
20cf0 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
20d00 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
20d10 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
20d20 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
20d30 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
20d40 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
20d50 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
20d60 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
20d70 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
20d80 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
20d90 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
20da0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
20db0 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
20dc0 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
20dd0 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
20de0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
20df0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
20e00 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
20e10 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
20e20 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
20e30 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
20e40 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
20e50 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
20e60 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
20e70 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
20e80 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
20e90 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
20ea0 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
20eb0 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
20ec0 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
20ed0 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
20ee0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
20ef0 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
20f00 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
20f10 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
20f20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
20f30 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
20f40 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
20f50 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
20f60 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
20f70 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
20f80 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
20f90 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
20fa0 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
20fb0 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
20fc0 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
20fd0 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
20fe0 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
20ff0 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
21000 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
21010 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
21020 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
21030 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
21040 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
21050 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
21060 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
21070 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
21080 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
21090 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
210a0 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
210b0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
210c0 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
210d0 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
210e0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
210f0 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
21100 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
21110 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
21120 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
21130 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
21140 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
21150 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
21160 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
21170 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
21180 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
21190 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
211a0 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64  =unix-nolock <td
211b0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70  >.**          Op
211c0 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66  en file "/home/f
211d0 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73  red/data.db". Us
211e0 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56 46  e the special VF
211f0 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e  S "unix-nolock".
21200 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
21210 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
21220 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
21230 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
21240 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
21250 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
21260 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
21270 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
21280 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
21290 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
212a0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
212b0 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
212c0 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
212d0 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
212e0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
212f0 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
21300 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
21310 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
21320 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
21330 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
21340 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
21350 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
21360 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
21370 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
21380 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
21390 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
213a0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
213b0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
213c0 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
213d0 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
213e0 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
213f0 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
21400 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
21410 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
21420 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
21430 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
21440 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
21450 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
21460 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
21470 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
21480 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
21490 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
214a0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
214b0 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
214c0 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
214d0 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
214e0 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
214f0 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
21500 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
21510 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
21520 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
21530 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
21540 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
21550 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
21560 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
21570 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
21580 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
21590 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
215a0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
215b0 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
215c0 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
215d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
215e0 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
215f0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
21600 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
21610 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
21620 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
21630 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
21640 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
21650 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
21660 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
21670 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
21680 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
21690 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
216a0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
216b0 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
216c0 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
216d0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
216e0 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
216f0 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51  directory].*/.SQ
21700 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
21710 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e  ite3_open(.  con
21720 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d  st char *filenam
21730 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
21740 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38   filename (UTF-8
21750 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
21760 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
21770 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
21780 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
21790 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
217a0 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63  ite3_open16(.  c
217b0 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e  onst void *filen
217c0 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
217d0 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
217e0 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  -16) */.  sqlite
217f0 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
21800 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
21810 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
21820 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
21830 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21840 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66  .  const char *f
21850 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
21860 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
21870 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c  (UTF-8) */.  sql
21880 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20  ite3 **ppDb,    
21890 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
218a0 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
218b0 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20  .  int flags,   
218c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c             /* Fl
218d0 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ags */.  const c
218e0 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20  har *zVfs       
218f0 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20   /* Name of VFS 
21900 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f  module to use */
21910 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
21920 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75  REF: Obtain Valu
21930 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d  es For URI Param
21940 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  eters.**.** Thes
21950 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f  e are utility ro
21960 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74  utines, useful t
21970 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  o VFS implementa
21980 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63  tions, that chec
21990 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61  k.** to see if a
219a0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
219b0 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f  as a URI that co
219c0 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66  ntained a specif
219d0 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72  ic query .** par
219e0 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73  ameter, and if s
219f0 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61  o obtains the va
21a00 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72  lue of that quer
21a10 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  y parameter..**.
21a20 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64  ** If F is the d
21a30 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
21a40 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20   pointer passed 
21a50 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  into the xOpen()
21a60 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61   method of .** a
21a70 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
21a80 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61  ion when the fla
21a90 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  gs parameter to 
21aa0 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20  xOpen() has one 
21ab0 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74  or .** more of t
21ac0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
21ad0 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  URI] or [SQLITE_
21ae0 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69  OPEN_MAIN_DB] bi
21af0 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20  ts set and.** P 
21b00 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
21b10 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  he query paramet
21b20 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  er, then.** sqli
21b30 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
21b40 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74  r(F,P) returns t
21b50 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
21b60 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  P.** parameter i
21b70 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61  f it exists or a
21b80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
21b90 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65   P does not appe
21ba0 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72  ar as a .** quer
21bb0 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  y parameter on F
21bc0 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65  .  If P is a que
21bd0 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ry parameter of 
21be0 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c  F.** has no expl
21bf0 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e  icit value, then
21c00 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
21c10 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
21c20 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  rns.** a pointer
21c30 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72   to an empty str
21c40 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ing..**.** The s
21c50 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
21c60 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
21c70 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50  e assumes that P
21c80 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a   is a boolean.**
21c90 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
21ca0 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20  eturns true (1) 
21cb0 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63  or false (0) acc
21cc0 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61  ording to the va
21cd0 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68  lue.** of P.  Th
21ce0 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
21cf0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
21d00 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75  tine returns tru
21d10 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20  e (1) if the.** 
21d20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70  value of query p
21d30 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
21d40 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75  e of "yes", "tru
21d50 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61  e", or "on" in a
21d60 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66  ny.** case or if
21d70 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e   the value begin
21d80 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72  s with a non-zer
21d90 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a  o number.  The .
21da0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
21db0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
21dc0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66  utines returns f
21dd0 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20  alse (0) if the 
21de0 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72  value of.** quer
21df0 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
21e00 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66   one of "no", "f
21e10 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20  alse", or "off" 
21e20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a  in any case or.*
21e30 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  * if the value b
21e40 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d  egins with a num
21e50 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50  eric zero.  If P
21e60 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a   is not a query.
21e70 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ** parameter on 
21e80 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  F or if the valu
21e90 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e  e of P is does n
21ea0 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20  ot match any of 
21eb0 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68  the.** above, th
21ec0 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  en sqlite3_uri_b
21ed0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
21ee0 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a  turns (B!=0)..**
21ef0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
21f00 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29  uri_int64(F,P,D)
21f10 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74   routine convert
21f20 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50  s the value of P
21f30 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69   into a.** 64-bi
21f40 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
21f50 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61   and returns tha
21f60 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20  t integer, or D 
21f70 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  if P does not.**
21f80 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20   exist.  If the 
21f90 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f  value of P is so
21fa0 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68  mething other th
21fb0 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  an an integer, t
21fc0 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72  hen.** zero is r
21fd0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20  eturned..** .** 
21fe0 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70  If F is a NULL p
21ff0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c  ointer, then sql
22000 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
22010 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
22020 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  NULL and.** sqli
22030 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
22040 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42  F,P,B) returns B
22050 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61  .  If F is not a
22060 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e   NULL pointer an
22070 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61  d.** is not a da
22080 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68  tabase file path
22090 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61  name pointer tha
220a0 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20  t SQLite passed 
220b0 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a  into the xOpen.*
220c0 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68  * VFS method, th
220d0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
220e0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  of this routine 
220f0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
22100 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64   probably.** und
22110 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c  esirable..*/.SQL
22120 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
22130 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f  ar *sqlite3_uri_
22140 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73 74 20  parameter(const 
22150 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c  char *zFilename,
22160 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
22170 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ram);.SQLITE_API
22180 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69   int sqlite3_uri
22190 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63  _boolean(const c
221a0 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73  har *zFile, cons
221b0 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20  t char *zParam, 
221c0 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 53  int bDefault);.S
221d0 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
221e0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
221f0 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
22200 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
22210 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
22220 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
22230 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
22240 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
22250 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
22260 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
22270 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
22280 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
22290 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
222a0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
222b0 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
222c0 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
222d0 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
222e0 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
222f0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
22300 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
22310 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
22320 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
22330 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
22340 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
22350 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
22360 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
22370 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
22380 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
22390 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
223a0 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
223b0 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
223c0 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
223d0 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
223e0 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
223f0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
22400 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
22410 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
22420 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
22430 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
22440 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
22450 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
22460 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
22470 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
22480 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
22490 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
224a0 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
224b0 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
224c0 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
224d0 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
224e0 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
224f0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
22500 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
22510 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
22520 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
22530 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
22540 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
22550 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
22560 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
22570 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
22580 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
22590 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
225a0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
225b0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
225c0 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
225d0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
225e0 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
225f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
22600 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
22610 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
22620 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
22630 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
22640 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
22650 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
22660 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
22670 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
22680 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
22690 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
226a0 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
226b0 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
226c0 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
226d0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
226e0 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
226f0 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
22700 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
22710 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
22720 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
22730 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
22740 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
22750 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
22760 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
22770 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
22780 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
22790 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
227a0 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
227b0 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
227c0 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
227d0 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
227e0 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
227f0 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
22800 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
22810 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
22820 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
22830 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
22840 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22850 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
22860 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
22870 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
22880 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
22890 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
228a0 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
228b0 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
228c0 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
228d0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
228e0 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
228f0 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
22900 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
22910 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
22920 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
22930 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
22940 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
22950 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
22960 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
22970 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
22980 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
22990 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
229a0 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
229b0 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
229c0 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
229d0 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
229e0 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
229f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72   int sqlite3_err
22a00 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
22a10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
22a20 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
22a30 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
22a40 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
22a50 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
22a60 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
22a70 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
22a80 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
22a90 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
22aa0 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  6(sqlite3*);.SQL
22ab0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
22ac0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 73  ar *sqlite3_errs
22ad0 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  tr(int);../*.** 
22ae0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
22af0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
22b00 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
22b10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
22b20 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
22b30 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
22b40 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
22b50 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
22b60 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
22b70 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
22b80 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
22b90 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
22ba0 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
22bb0 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
22bc0 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
22bd0 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
22be0 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
22bf0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
22c00 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
22c10 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
22c20 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
22c30 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
22c40 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
22c50 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
22c60 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22c70 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
22c80 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
22c90 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
22ca0 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
22cb0 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
22cc0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
22cd0 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
22ce0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
22cf0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
22d00 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
22d10 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
22d20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
22d30 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
22d40 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
22d50 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
22d60 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
22d70 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
22d80 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
22d90 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
22da0 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
22db0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
22dc0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
22dd0 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
22de0 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
22df0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
22e00 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
22e10 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
22e20 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
22e30 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
22e40 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
22e50 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
22e60 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
22e70 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
22e80 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  imits.**.** ^(Th
22e90 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
22ea0 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
22eb0 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
22ec0 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
22ed0 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
22ee0 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
22ef0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
22f00 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
22f10 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
22f20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
22f30 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
22f40 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
22f50 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
22f60 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
22f70 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
22f80 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
22f90 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
22fa0 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
22fb0 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
22fc0 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
22fd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
22fe0 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
22ff0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
23000 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
23010 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
23020 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
23030 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
23040 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
23050 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
23060 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
23070 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
23080 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
23090 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
230a0 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
230b0 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
230c0 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
230d0 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
230e0 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
230f0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
23100 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
23110 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
23120 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
23130 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
23140 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
23150 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
23160 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
23170 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
23180 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
23190 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
231a0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
231b0 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
231c0 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
231d0 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
231e0 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
231f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
23200 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
23210 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
23220 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
23230 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
23240 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
23250 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
23260 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
23270 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
23280 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
23290 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
232a0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
232b0 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
232c0 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
232d0 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
232e0 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
232f0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
23300 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
23310 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
23320 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
23330 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
23340 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
23350 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
23360 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
23370 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
23380 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
23390 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
233a0 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
233b0 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
233c0 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
233d0 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
233e0 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
233f0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
23400 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
23410 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
23420 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
23430 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
23440 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
23450 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
23460 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
23470 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
23480 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
23490 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
234a0 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
234b0 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
234c0 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
234d0 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
234e0 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
234f0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
23500 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
23510 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
23520 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
23530 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
23540 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
23550 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
23560 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
23570 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
23580 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
23590 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
235a0 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
235b0 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
235c0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
235d0 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
235e0 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
235f0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
23600 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
23610 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
23620 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
23630 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28  t sqlite3_limit(
23640 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64  sqlite3*, int id
23650 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a  , int newVal);..
23660 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
23670 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43  Run-Time Limit C
23680 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59  ategories.** KEY
23690 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61  WORDS: {limit ca
236a0 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20  tegory} {*limit 
236b0 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a  categories}.**.*
236c0 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
236d0 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73  s define various
236e0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d   performance lim
236f0 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20  its.** that can 
23700 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75  be lowered at ru
23710 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71  n-time using [sq
23720 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a  lite3_limit()]..
23730 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20  ** The synopsis 
23740 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20  of the meanings 
23750 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  of the various l
23760 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62  imits is shown b
23770 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f  elow..** Additio
23780 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  nal information 
23790 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20  is available at 
237a0 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73  [limits | Limits
237b0 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a   in SQLite]..**.
237c0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
237d0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
237e0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
237f0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74  LIMIT_LENGTH</dt
23800 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
23810 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79  imum size of any
23820 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
23830 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e  or table row, in
23840 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a   bytes.<dd>)^.**
23850 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
23860 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20  IT_SQL_LENGTH]] 
23870 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
23880 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64  IT_SQL_LENGTH</d
23890 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
238a0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
238b0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
238c0 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e  , in bytes.</dd>
238d0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
238e0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d  E_LIMIT_COLUMN]]
238f0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
23900 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a  MIT_COLUMN</dt>.
23910 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
23920 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
23930 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20  umns in a table 
23940 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e  definition or in
23950 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73   the.** result s
23960 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
23970 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   or the maximum 
23980 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
23990 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a  s in an index.**
239a0 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20   or in an ORDER 
239b0 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63  BY or GROUP BY c
239c0 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  lause.</dd>)^.**
239d0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
239e0 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20  IT_EXPR_DEPTH]] 
239f0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
23a00 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64  IT_EXPR_DEPTH</d
23a10 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
23a20 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74  ximum depth of t
23a30 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e  he parse tree on
23a40 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e   any expression.
23a50 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
23a60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
23a70 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e  POUND_SELECT]] ^
23a80 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
23a90 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
23aa0 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  T</dt>.** <dd>Th
23ab0 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
23ac0 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63   of terms in a c
23ad0 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73  ompound SELECT s
23ae0 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e  tatement.</dd>)^
23af0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
23b00 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20  LIMIT_VDBE_OP]] 
23b10 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
23b20 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a  IT_VDBE_OP</dt>.
23b30 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
23b40 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73  um number of ins
23b50 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76  tructions in a v
23b60 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70  irtual machine p
23b70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74  rogram.** used t
23b80 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53  o implement an S
23b90 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54  QL statement.  T
23ba0 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  his limit is not
23bb0 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e   currently.** en
23bc0 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74  forced, though t
23bd0 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64 64  hat might be add
23be0 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72  ed in some futur
23bf0 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20  e release of.** 
23c00 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  SQLite.</dd>)^.*
23c10 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
23c20 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
23c30 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
23c40 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
23c50 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  RG</dt>.** <dd>T
23c60 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
23c70 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f  r of arguments o
23c80 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64  n a function.</d
23c90 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
23ca0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
23cb0 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ED]] ^(<dt>SQLIT
23cc0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
23cd0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
23ce0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
23cf0 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74  of [ATTACH | att
23d00 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73 5d  ached databases]
23d10 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  .)^</dd>.**.** [
23d20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  [SQLITE_LIMIT_LI
23d30 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
23d40 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c  H]].** ^(<dt>SQL
23d50 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
23d60 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64  ATTERN_LENGTH</d
23d70 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
23d80 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
23d90 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67 75  the pattern argu
23da0 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b  ment to the [LIK
23db0 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20  E] or.** [GLOB] 
23dc0 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29  operators.</dd>)
23dd0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
23de0 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
23df0 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64  NUMBER]].** ^(<d
23e00 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
23e10 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
23e20 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
23e30 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d  aximum index num
23e40 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61  ber of any [para
23e50 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c  meter] in an SQL
23e60 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a   statement.)^.**
23e70 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
23e80 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
23e90 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
23ea0 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
23eb0 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  PTH</dt>.** <dd>
23ec0 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74  The maximum dept
23ed0 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66  h of recursion f
23ee0 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64  or triggers.</dd
23ef0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  >)^.** </dl>.*/.
23f00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
23f10 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20  IMIT_LENGTH     
23f20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
23f30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
23f40 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
23f50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23f60 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
23f70 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20  _LIMIT_COLUMN   
23f80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23f90 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
23fa0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
23fb0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
23fc0 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
23fd0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
23fe0 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  D_SELECT        
23ff0 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
24000 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
24010 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  P               
24020 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
24030 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
24040 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20  ION_ARG         
24050 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53       6.#define S
24060 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
24070 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20 20  CHED            
24080 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20        7.#define 
24090 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
240a0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
240b0 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
240c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41   SQLITE_LIMIT_VA
240d0 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20  RIABLE_NUMBER   
240e0 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
240f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  e SQLITE_LIMIT_T
24100 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20 20  RIGGER_DEPTH    
24110 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a          10../*.*
24120 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70  * CAPI3REF: Comp
24130 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61  iling An SQL Sta
24140 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52  tement.** KEYWOR
24150 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65  DS: {SQL stateme
24160 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a  nt compiler}.**.
24170 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e  ** To execute an
24180 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d   SQL query, it m
24190 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d  ust first be com
241a0 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74  piled into a byt
241b0 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61  e-code.** progra
241c0 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74  m using one of t
241d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  hese routines..*
241e0 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
241f0 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69  rgument, "db", i
24200 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f  s a [database co
24210 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e  nnection] obtain
24220 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69  ed from a.** pri
24230 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  or successful ca
24240 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ll to [sqlite3_o
24250 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
24260 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a  _open_v2()] or.*
24270 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  * [sqlite3_open1
24280 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62  6()].  The datab
24290 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
242a0 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65  ust not have bee
242b0 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  n closed..**.** 
242c0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
242d0 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20  ent, "zSql", is 
242e0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  the statement to
242f0 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e   be compiled, en
24300 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68  coded.** as eith
24310 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
24320 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  16.  The sqlite3
24330 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20 73  _prepare() and s
24340 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
24350 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  2().** interface
24360 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64  s use UTF-8, and
24370 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
24380 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  16() and sqlite3
24390 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a  _prepare16_v2().
243a0 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a  ** use UTF-16..*
243b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79  *.** ^If the nBy
243c0 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c  te argument is l
243d0 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74  ess than zero, t
243e0 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64  hen zSql is read
243f0 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69   up to the.** fi
24400 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
24410 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69  tor. ^If nByte i
24420 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
24430 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d  then it is the m
24440 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72  aximum.** number
24450 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64 20   of  bytes read 
24460 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65  from zSql.  ^Whe
24470 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e  n nByte is non-n
24480 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20  egative, the.** 
24490 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73  zSql string ends
244a0 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20 66   at either the f
244b0 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27  irst '\000' or '
244c0 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74 65  \u0000' characte
244d0 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74  r or.** the nByt
244e0 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63 68  e-th byte, which
244f0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
24500 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20  . If the caller 
24510 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68  knows.** that th
24520 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e  e supplied strin
24530 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  g is nul-termina
24540 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20  ted, then there 
24550 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65  is a small.** pe
24560 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74  rformance advant
24570 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64  age to be gained
24580 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e   by passing an n
24590 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20 74  Byte parameter t
245a0 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20  hat.** is equal 
245b0 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  to the number of
245c0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e   bytes in the in
245d0 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e  put string <i>in
245e0 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74  cluding</i>.** t
245f0 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f  he nul-terminato
24600 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73 20  r bytes as this 
24610 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f  saves SQLite fro
24620 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d  m having to.** m
24630 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ake a copy of th
24640 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a  e input string..
24650 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c  **.** ^If pzTail
24660 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65   is not NULL the
24670 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64  n *pzTail is mad
24680 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68  e to point to th
24690 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20  e first byte.** 
246a0 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20  past the end of 
246b0 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73 74  the first SQL st
246c0 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e  atement in zSql.
246d0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
246e0 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65   only.** compile
246f0 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74 65   the first state
24700 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f  ment in zSql, so
24710 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74   *pzTail is left
24720 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20   pointing to.** 
24730 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63  what remains unc
24740 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ompiled..**.** ^
24750 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20  *ppStmt is left 
24760 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f  pointing to a co
24770 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64  mpiled [prepared
24780 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
24790 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75   can be.** execu
247a0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
247b0 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66  e3_step()].  ^If
247c0 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72 72   there is an err
247d0 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73  or, *ppStmt is s
247e0 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20  et.** to NULL.  
247f0 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74 65  ^If the input te
24800 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53  xt contains no S
24810 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75 74  QL (if the input
24820 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20   is an empty.** 
24830 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d  string or a comm
24840 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d  ent) then *ppStm
24850 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c  t is set to NULL
24860 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67  ..** The calling
24870 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72 65   procedure is re
24880 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65  sponsible for de
24890 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  leting the compi
248a0 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  led.** SQL state
248b0 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ment using [sqli
248c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
248d0 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69 6e  after it has fin
248e0 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a  ished with it..*
248f0 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74  * ppStmt may not
24900 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
24910 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65  ^On success, the
24920 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
24930 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75  () family of rou
24940 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51  tines return [SQ
24950 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68  LITE_OK];.** oth
24960 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72  erwise an [error
24970 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e   code] is return
24980 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
24990 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
249a0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
249b0 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e  repare16_v2() in
249c0 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20  terfaces are.** 
249d0 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
249e0 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73  all new programs
249f0 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20  . The two older 
24a00 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 72  interfaces are r
24a10 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62  etained.** for b
24a20 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
24a30 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69  bility, but thei
24a40 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75 72  r use is discour
24a50 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65  aged..** ^In the
24a60 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 73   "v2" interfaces
24a70 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73  , the prepared s
24a80 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74  tatement.** that
24a90 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74 68   is returned (th
24aa0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
24ab0 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e   object) contain
24ac0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
24ad0 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20  ** original SQL 
24ae0 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73 65  text. This cause
24af0 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  s the [sqlite3_s
24b00 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tep()] interface
24b10 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69   to.** behave di
24b20 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72  fferently in thr
24b30 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ee ways:.**.** <
24b40 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  ol>.** <li>.** ^
24b50 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
24b60 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20  schema changes, 
24b70 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75 72  instead of retur
24b80 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48  ning [SQLITE_SCH
24b90 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c  EMA] as it.** al
24ba0 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c  ways used to do,
24bb0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
24bc0 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  ] will automatic
24bd0 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74  ally recompile t
24be0 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d  he SQL.** statem
24bf0 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72  ent and try to r
24c00 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20  un it again..** 
24c10 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
24c20 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72  .** ^When an err
24c30 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69  or occurs, [sqli
24c40 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
24c50 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74   return one of t
24c60 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b  he detailed.** [
24c70 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20  error codes] or 
24c80 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
24c90 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65  codes].  ^The le
24ca0 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77 61  gacy behavior wa
24cb0 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74  s that.** [sqlit
24cc0 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64  e3_step()] would
24cd0 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67   only return a g
24ce0 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45  eneric [SQLITE_E
24cf0 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64  RROR] result cod
24d00 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70  e.** and the app
24d10 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68  lication would h
24d20 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65  ave to make a se
24d30 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71  cond call to [sq
24d40 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a  lite3_reset()].*
24d50 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  * in order to fi
24d60 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
24d70 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  g cause of the p
24d80 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65  roblem. With the
24d90 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a   "v2" prepare.**
24da0 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65   interfaces, the
24db0 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73   underlying reas
24dc0 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72  on for the error
24dd0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d   is returned imm
24de0 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c  ediately..** </l
24df0 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
24e00 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66 69   ^If the specifi
24e10 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f  c value bound to
24e20 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f   [parameter | ho
24e30 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  st parameter] in
24e40 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63   the .** WHERE c
24e50 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c  lause might infl
24e60 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65  uence the choice
24e70 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66   of query plan f
24e80 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a  or a statement,.
24e90 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61 74  ** then the stat
24ea0 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75  ement will be au
24eb0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f  tomatically reco
24ec0 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68  mpiled, as if th
24ed0 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a  ere had been .**
24ee0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
24ef0 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20  , on the first  
24f00 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
24f10 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20   call following 
24f20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f  any change.** to
24f30 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
24f40 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e  nd_text | bindin
24f50 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72  gs] of that [par
24f60 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68  ameter]. .** ^Th
24f70 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65  e specific value
24f80 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65   of WHERE-clause
24f90 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67   [parameter] mig
24fa0 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65  ht influence the
24fb0 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71   .** choice of q
24fc0 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65  uery plan if the
24fd0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
24fe0 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65  e left-hand side
24ff0 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20   of a [LIKE].** 
25000 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  or [GLOB] operat
25010 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61 72  or or if the par
25020 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72  ameter is compar
25030 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64  ed to an indexed
25040 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74   column.** and t
25050 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
25060 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65  E_STAT3] compile
25070 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20  -time option is 
25080 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20  enabled..** the 
25090 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f  .** </li>.** </o
250a0 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
250b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
250c0 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20  pare(.  sqlite3 
250d0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
250e0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
250f0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
25100 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
25110 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
25120 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
25130 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
25140 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
25150 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
25160 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
25170 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
25180 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
25190 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
251a0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
251b0 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
251c0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
251d0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
251e0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
251f0 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
25200 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
25210 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
25220 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
25230 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
25240 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
25250 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
25260 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
25270 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
25280 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
25290 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
252a0 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
252b0 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
252c0 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
252d0 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
252e0 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
252f0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
25300 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
25310 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
25320 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
25330 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
25340 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
25350 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
25360 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74 65 33  are16(.  sqlite3
25370 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
25380 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
25390 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
253a0 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
253b0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
253c0 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
253d0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
253e0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
253f0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
25400 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
25410 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
25420 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
25430 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
25440 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
25450 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
25460 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
25470 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
25480 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
25490 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
254a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
254b0 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c  pare16_v2(.  sql
254c0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
254d0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
254e0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
254f0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
25500 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
25510 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
25520 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
25530 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
25540 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
25550 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
25560 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
25570 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
25580 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
25590 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
255a0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
255b0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
255c0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
255d0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
255e0 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  Sql */.);../*.**
255f0 20 43 41 50 49 33 52 45 46 3a 20 52 65 74 72 69   CAPI3REF: Retri
25600 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20  eving Statement 
25610 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  SQL.**.** ^This 
25620 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
25630 20 75 73 65 64 20 74 6f 20 72 65 74 72 69 65 76   used to retriev
25640 65 20 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f  e a saved copy o
25650 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a  f the original.*
25660 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65 64 20  * SQL text used 
25670 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70 72 65  to create a [pre
25680 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
25690 20 69 66 20 74 68 61 74 20 73 74 61 74 65 6d 65   if that stateme
256a0 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c  nt was.** compil
256b0 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ed using either 
256c0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
256d0 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
256e0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
256f0 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
25700 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
25710 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65  lite3_sql(sqlite
25720 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
25730 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25740 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
25750 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57   SQL Statement W
25760 72 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61  rites The Databa
25770 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  se.**.** ^The sq
25780 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
25790 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65  nly(X) interface
257a0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e   returns true (n
257b0 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61  on-zero) if.** a
257c0 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b  nd only if the [
257d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
257e0 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64  nt] X makes no d
257f0 69 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f  irect changes to
25800 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
25810 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  of the database 
25820 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  file..**.** Note
25830 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69   that [applicati
25840 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
25850 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20  unctions] or.** 
25860 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d  [virtual tables]
25870 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68   might change th
25880 65 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72  e database indir
25890 65 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20  ectly as a side 
258a0 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46  effect.  .** ^(F
258b0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61  or example, if a
258c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  n application de
258d0 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e  fines a function
258e0 20 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a   "eval()" that .
258f0 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65  ** calls [sqlite
25900 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20  3_exec()], then 
25910 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  the following SQ
25920 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c  L statement woul
25930 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  d.** change the 
25940 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68  database file th
25950 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63  rough side-effec
25960 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ts:.**.** <block
25970 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
25980 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44    SELECT eval('D
25990 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20  ELETE FROM t1') 
259a0 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72  FROM t2;.** </pr
259b0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
259c0 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73  **.** But becaus
259d0 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  e the [SELECT] s
259e0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
259f0 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  t change the dat
25a00 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69  abase file.** di
25a10 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f  rectly, sqlite3_
25a20 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
25a30 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75  would still retu
25a40 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a  rn true.)^.**.**
25a50 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f   ^Transaction co
25a60 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73  ntrol statements
25a70 20 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d   such as [BEGIN]
25a80 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c  , [COMMIT], [ROL
25a90 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45  LBACK],.** [SAVE
25aa0 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c  POINT], and [REL
25ab0 45 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69  EASE] cause sqli
25ac0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
25ad0 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
25ae0 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65  ue,.** since the
25af0 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d   statements them
25b00 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63  selves do not ac
25b10 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68  tually modify th
25b20 65 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a  e database but.*
25b30 2a 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f  * rather they co
25b40 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67  ntrol the timing
25b50 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73   of when other s
25b60 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79  tatements modify
25b70 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73   the .** databas
25b80 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48  e.  ^The [ATTACH
25b90 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73  ] and [DETACH] s
25ba0 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63  tatements also c
25bb0 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ause.** sqlite3_
25bc0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
25bd0 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73  to return true s
25be0 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73  ince, while thos
25bf0 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  e statements.** 
25c00 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69  change the confi
25c10 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61  guration of a da
25c20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
25c30 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d  n, they do not m
25c40 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20  ake .** changes 
25c50 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  to the content o
25c60 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
25c70 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f  iles on disk..*/
25c80 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
25c90 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
25ca0 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73 74  donly(sqlite3_st
25cb0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
25cc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
25cd0 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72 65 70  ermine If A Prep
25ce0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 48  ared Statement H
25cf0 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a  as Been Reset.**
25d00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
25d10 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20 69 6e  _stmt_busy(S) in
25d20 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
25d30 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20  true (non-zero) 
25d40 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  if the.** [prepa
25d50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
25d60 20 68 61 73 20 62 65 65 6e 20 73 74 65 70 70 65   has been steppe
25d70 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63 65 20  d at least once 
25d80 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
25d90 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75 74 20  e3_step(S)] but 
25da0 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63  has not run to c
25db0 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72  ompletion and/or
25dc0 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65   has not .** bee
25dd0 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20 5b 73  n reset using [s
25de0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
25df0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
25e00 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20  stmt_busy(S).** 
25e10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
25e20 73 20 66 61 6c 73 65 20 69 66 20 53 20 69 73 20  s false if S is 
25e30 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
25e40 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61 20 0a   If S is not a .
25e50 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
25e60 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 6f 69  and is not a poi
25e70 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69 64 20  nter to a valid 
25e80 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25e90 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20  ent].** object, 
25ea0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
25eb0 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  r is undefined a
25ec0 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
25ed0 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54  sirable..**.** T
25ee0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
25ef0 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63 6f 6d  n be used in com
25f00 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65  bination [sqlite
25f10 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a  3_next_stmt()].*
25f20 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20  * to locate all 
25f30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25f40 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64 20 77  nts associated w
25f50 69 74 68 20 61 20 64 61 74 61 62 61 73 65 20 0a  ith a database .
25f60 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
25f70 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64 20 6f  at are in need o
25f80 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e 20 20  f being reset.  
25f90 54 68 69 73 20 63 61 6e 20 62 65 20 75 73 65 64  This can be used
25fa0 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65  ,.** for example
25fb0 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69 63 20  , in diagnostic 
25fc0 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65 61 72  routines to sear
25fd0 63 68 20 66 6f 72 20 70 72 65 70 61 72 65 64 20  ch for prepared 
25fe0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 74  .** statements t
25ff0 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e 67 20  hat are holding 
26000 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70  a transaction op
26010 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  en..*/.SQLITE_AP
26020 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
26030 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65 33 5f  mt_busy(sqlite3_
26040 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
26050 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d 69 63  API3REF: Dynamic
26060 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c 75 65  ally Typed Value
26070 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
26080 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65 64 20  RDS: {protected 
26090 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b  sqlite3_value} {
260a0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
260b0 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a  te3_value}.**.**
260c0 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
260d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
260e0 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65 73 65  bject to represe
260f0 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a  nt all values.**
26100 20 74 68 61 74 20 63 61 6e 20 62 65 20 73 74 6f   that can be sto
26110 72 65 64 20 69 6e 20 61 20 64 61 74 61 62 61 73  red in a databas
26120 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74 65 20  e table. SQLite 
26130 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74 79 70  uses dynamic typ
26140 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76  ing.** for the v
26150 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65 73 2e  alues it stores.
26160 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72 65 64    ^Values stored
26170 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   in sqlite3_valu
26180 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e  e objects.** can
26190 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20 66 6c   be integers, fl
261a0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
261b0 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c  ues, strings, BL
261c0 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a  OBs, or NULL..**
261d0 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33 5f 76  .** An sqlite3_v
261e0 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61 79 20  alue object may 
261f0 62 65 20 65 69 74 68 65 72 20 22 70 72 6f 74 65  be either "prote
26200 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72 6f 74  cted" or "unprot
26210 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20  ected"..** Some 
26220 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
26230 72 65 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  re a protected s
26240 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f  qlite3_value.  O
26250 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 0a  ther interfaces.
26260 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74 20 65  ** will accept e
26270 69 74 68 65 72 20 61 20 70 72 6f 74 65 63 74 65  ither a protecte
26280 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63  d or an unprotec
26290 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
262a0 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e 74 65  e..** Every inte
262b0 72 66 61 63 65 20 74 68 61 74 20 61 63 63 65 70  rface that accep
262c0 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ts sqlite3_value
262d0 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65 63 69   arguments speci
262e0 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65 72 20  fies.** whether 
262f0 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75 69 72  or not it requir
26300 65 73 20 61 20 70 72 6f 74 65 63 74 65 64 20 73  es a protected s
26310 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a  qlite3_value..**
26320 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20 22 70  .** The terms "p
26330 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20 22 75  rotected" and "u
26340 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65 66 65  nprotected" refe
26350 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f 72 20  r to whether or 
26360 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69  not.** a mutex i
26370 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65  s held.  An inte
26380 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20 68 65  rnal mutex is he
26390 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65 63 74  ld for a protect
263a0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
263b0 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74 20 6e  lue object but n
263c0 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  o mutex is held 
263d0 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74  for an unprotect
263e0 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
263f0 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49 66 20  lue object.  If 
26400 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
26410 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d  ed to be single-
26420 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77 69 74  threaded.** (wit
26430 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  h [SQLITE_THREAD
26440 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69 74 68  SAFE=0] and with
26450 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64   [sqlite3_thread
26460 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e 69 6e  safe()] returnin
26470 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51  g 0).** or if SQ
26480 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e 20 6f  Lite is run in o
26490 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20 6d 75  ne of reduced mu
264a0 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53  tex modes .** [S
264b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
264c0 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20 5b 53  GLETHREAD] or [S
264d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
264e0 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65  TITHREAD].** the
264f0 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69  n there is no di
26500 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
26510 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
26520 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
26530 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26540 65 63 74 73 20 61 6e 64 20 74 68 65 79 20 63 61  ects and they ca
26550 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65 72 63  n be used interc
26560 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f 77 65  hangeably.  Howe
26570 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69  ver,.** for maxi
26580 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61 62 69  mum code portabi
26590 6c 69 74 79 20 69 74 20 69 73 20 72 65 63 6f 6d  lity it is recom
265a0 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c  mended that appl
265b0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c  ications.** stil
265c0 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69  l make the disti
265d0 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
265e0 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
265f0 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
26600 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
26610 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20  s even when not 
26620 73 74 72 69 63 74 6c 79 20 72 65 71 75 69 72 65  strictly require
26630 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
26640 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
26650 63 74 73 20 74 68 61 74 20 61 72 65 20 70 61 73  cts that are pas
26660 73 65 64 20 61 73 20 70 61 72 61 6d 65 74 65 72  sed as parameter
26670 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d  s into the.** im
26680 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
26690 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
266a0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
266b0 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63 74 65  ns] are protecte
266c0 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  d..** ^The sqlit
266d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
266e0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
266f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
26700 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70 72 6f  alue()] is unpro
26710 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f  tected..** Unpro
26720 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
26730 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d 61 79  alue objects may
26740 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
26750 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  th.** [sqlite3_r
26760 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61  esult_value()] a
26770 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
26780 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68  _value()]..** Th
26790 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
267a0 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f  _blob | sqlite3_
267b0 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20 66 61  value_type()] fa
267c0 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  mily of.** inter
267d0 66 61 63 65 73 20 72 65 71 75 69 72 65 20 70 72  faces require pr
267e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
267f0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a  value objects..*
26800 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
26810 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c   Mem sqlite3_val
26820 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  ue;../*.** CAPI3
26830 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f  REF: SQL Functio
26840 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74  n Context Object
26850 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65  .**.** The conte
26860 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e 20 53  xt in which an S
26870 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78 65 63  QL function exec
26880 75 74 65 73 20 69 73 20 73 74 6f 72 65 64 20 69  utes is stored i
26890 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n an.** sqlite3_
268a0 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 2e 20  context object. 
268b0 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61   ^A pointer to a
268c0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  n sqlite3_contex
268d0 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61  t object.** is a
268e0 6c 77 61 79 73 20 66 69 72 73 74 20 70 61 72 61  lways first para
268f0 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c 69 63  meter to [applic
26900 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
26910 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  L functions]..**
26920 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
26930 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
26940 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
26950 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73 20 74  tion will pass t
26960 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  his.** pointer t
26970 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c  hrough into call
26980 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
26990 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74  sult_int | sqlit
269a0 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a  e3_result()],.**
269b0 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   [sqlite3_aggreg
269c0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20  ate_context()], 
269d0 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
269e0 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ta()],.** [sqlit
269f0 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
26a00 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ndle()], [sqlite
26a10 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_get_auxdata()]
26a20 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c  ,.** and/or [sql
26a30 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
26a40 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ()]..*/.typedef 
26a50 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 63  struct sqlite3_c
26a60 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33 5f 63  ontext sqlite3_c
26a70 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ontext;../*.** C
26a80 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69 6e 67  API3REF: Binding
26a90 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65 70 61   Values To Prepa
26aa0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a  red Statements.*
26ab0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73  * KEYWORDS: {hos
26ac0 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f  t parameter} {ho
26ad0 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  st parameters} {
26ae0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e  host parameter n
26af0 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ame}.** KEYWORDS
26b00 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  : {SQL parameter
26b10 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  } {SQL parameter
26b20 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20 62 69  s} {parameter bi
26b30 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49  nding}.**.** ^(I
26b40 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  n the SQL statem
26b50 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74 20 74  ent text input t
26b60 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  o [sqlite3_prepa
26b70 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69 74 73  re_v2()] and its
26b80 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69   variants,.** li
26b90 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20 72 65  terals may be re
26ba0 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70 61 72  placed by a [par
26bb0 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d 61 74  ameter] that mat
26bc0 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c  ches one of foll
26bd0 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74  owing.** templat
26be0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
26bf0 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69  * <li>  ?.** <li
26c00 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20  >  ?NNN.** <li> 
26c10 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40   :VVV.** <li>  @
26c20 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56  VVV.** <li>  $VV
26c30 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  V.** </ul>.**.**
26c40 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61 74 65   In the template
26c50 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70  s above, NNN rep
26c60 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74 65 67  resents an integ
26c70 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61  er literal,.** a
26c80 6e 64 20 56 56 56 20 72 65 70 72 65 73 65 6e 74  nd VVV represent
26c90 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69  s an alphanumeri
26ca0 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29 5e 20  c identifier.)^ 
26cb0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f 66 20   ^The values of 
26cc0 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74  these.** paramet
26cd0 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64  ers (also called
26ce0 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   "host parameter
26cf0 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51 4c 20   names" or "SQL 
26d00 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20  parameters").** 
26d10 63 61 6e 20 62 65 20 73 65 74 20 75 73 69 6e 67  can be set using
26d20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
26d30 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 64  d_*() routines d
26d40 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a  efined here..**.
26d50 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72  ** ^The first ar
26d60 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71  gument to the sq
26d70 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
26d80 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77 61 79  outines is alway
26d90 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74  s.** a pointer t
26da0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  o the [sqlite3_s
26db0 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65 74 75  tmt] object retu
26dc0 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71  rned from.** [sq
26dd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
26de0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
26df0 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
26e00 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
26e10 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
26e20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65 74 65  the SQL paramete
26e30 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20  r to be set..** 
26e40 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 53 51  ^The leftmost SQ
26e50 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  L parameter has 
26e60 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e 20 20  an index of 1.  
26e70 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65 20 6e  ^When the same n
26e80 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61  amed.** SQL para
26e90 6d 65 74 65 72 20 69 73 20 75 73 65 64 20 6d 6f  meter is used mo
26ea0 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65  re than once, se
26eb0 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75  cond and subsequ
26ec0 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63  ent.** occurrenc
26ed0 65 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65  es have the same
26ee0 20 69 6e 64 65 78 20 61 73 20 74 68 65 20 66 69   index as the fi
26ef0 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a  rst occurrence..
26f00 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20 66 6f  ** ^The index fo
26f10 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65  r named paramete
26f20 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64  rs can be looked
26f30 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a   up using the.**
26f40 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
26f50 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
26f60 5d 20 41 50 49 20 69 66 20 64 65 73 69 72 65 64  ] API if desired
26f70 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a  .  ^The index.**
26f80 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61   for "?NNN" para
26f90 6d 65 74 65 72 73 20 69 73 20 74 68 65 20 76 61  meters is the va
26fa0 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e  lue of NNN..** ^
26fb0 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75  The NNN value mu
26fc0 73 74 20 62 65 20 62 65 74 77 65 65 6e 20 31 20  st be between 1 
26fd0 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33  and the [sqlite3
26fe0 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72  _limit()].** par
26ff0 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c  ameter [SQLITE_L
27000 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
27010 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74 20 76  MBER] (default v
27020 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a  alue: 999)..**.*
27030 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67  * ^The third arg
27040 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76 61 6c  ument is the val
27050 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20 74 68  ue to bind to th
27060 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  e parameter..**.
27070 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f  ** ^(In those ro
27080 75 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65  utines that have
27090 20 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65   a fourth argume
270a0 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73  nt, its value is
270b0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
270c0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70  f bytes in the p
270d0 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65  arameter.  To be
270e0 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75   clear: the valu
270f0 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
27100 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f  er of <u>bytes</
27110 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c  u> in the value,
27120 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
27130 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e  of characters.)^
27140 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72  .** ^If the four
27150 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
27160 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27170 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  t() or sqlite3_b
27180 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  ind_text16().** 
27190 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
271a0 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  n the length of 
271b0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
271c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
271d0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
271e0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
271f0 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ator..** If the 
27200 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
27210 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
27220 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74  _blob() is negat
27230 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  ive, then.** the
27240 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
27250 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20  efined..** If a 
27260 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75  non-negative fou
27270 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
27280 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c   provided to sql
27290 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
272a0 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
272b0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65  ind_text16() the
272c0 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72  n that parameter
272d0 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74   must be the byt
272e0 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72  e offset.** wher
272f0 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
27300 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72  ator would occur
27310 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74   assuming the st
27320 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a  ring were NUL.**
27330 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
27340 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
27350 65 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74  ers occur at byt
27360 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74  e offsets less t
27370 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75  han .** the valu
27380 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20  e of the fourth 
27390 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74  parameter then t
273a0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
273b0 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a  ing value will.*
273c0 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64  * contain embedd
273d0 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65  ed NULs.  The re
273e0 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69  sult of expressi
273f0 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74  ons involving st
27400 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d  rings.** with em
27410 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75  bedded NULs is u
27420 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
27430 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
27440 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
27450 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  ind_blob(), sqli
27460 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
27470 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
27480 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73  bind_text16() is
27490 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
274a0 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
274b0 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
274c0 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
274d0 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
274e0 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
274f0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
27500 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
27510 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
27520 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
27530 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c   the call to sql
27540 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
27550 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  ,.** sqlite3_bin
27560 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c  d_text(), or sql
27570 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
27580 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e  () fails.  .** ^
27590 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
275a0 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
275b0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
275c0 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
275d0 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
275e0 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
275f0 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
27600 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
27610 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
27620 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
27630 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
27640 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
27650 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
27660 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
27670 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
27680 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
27690 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
276a0 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
276b0 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
276c0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
276d0 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
276e0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
276f0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
27700 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
27710 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
27720 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
27730 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
27740 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
27750 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
27760 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
27770 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
27780 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
27790 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
277a0 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
277b0 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
277c0 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
277d0 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
277e0 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
277f0 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
27800 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
27810 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
27820 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
27830 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
27840 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
27850 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
27860 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
27870 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
27880 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
27890 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
278a0 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
278b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
278c0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
278d0 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
278e0 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
278f0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
27900 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
27910 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
27920 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
27930 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
27940 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
27950 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
27960 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
27970 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
27980 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
27990 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
279a0 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
279b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
279c0 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
279d0 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
279e0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
279f0 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
27a00 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
27a10 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
27a20 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
27a30 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
27a40 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
27a50 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
27a60 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
27a70 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
27a80 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
27a90 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
27aa0 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
27ab0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
27ac0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
27ad0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
27ae0 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
27af0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
27b00 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
27b10 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
27b20 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
27b30 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
27b40 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
27b50 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
27b60 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
27b70 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
27b80 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
27b90 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
27ba0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
27bb0 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
27bc0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
27bd0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
27be0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
27bf0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
27c00 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
27c10 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
27c20 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28  lite3_bind_blob(
27c30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
27c40 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  nt, const void*,
27c50 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
27c60 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
27c70 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
27c80 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69  bind_double(sqli
27c90 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
27ca0 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f  double);.SQLITE_
27cb0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
27cc0 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33  bind_int(sqlite3
27cd0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74  _stmt*, int, int
27ce0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
27cf0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
27d00 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
27d10 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33  t*, int, sqlite3
27d20 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f  _int64);.SQLITE_
27d30 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
27d40 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  bind_null(sqlite
27d50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53  3_stmt*, int);.S
27d60 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
27d70 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
27d80 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
27d90 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
27da0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
27db0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
27dc0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
27dd0 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
27de0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
27df0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
27e00 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
27e10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
27e20 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76  t sqlite3_bind_v
27e30 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
27e40 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73  t*, int, const s
27e50 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
27e60 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27e70 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
27e80 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
27e90 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b  t*, int, int n);
27ea0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27eb0 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20  : Number Of SQL 
27ec0 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a  Parameters.**.**
27ed0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63   ^This routine c
27ee0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69  an be used to fi
27ef0 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  nd the number of
27f00 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73   [SQL parameters
27f10 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61  ].** in a [prepa
27f20 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
27f30 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20   SQL parameters 
27f40 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68  are tokens of th
27f50 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22  e.** form "?", "
27f60 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22  ?NNN", ":AAA", "
27f70 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22  $AAA", or "@AAA"
27f80 20 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a   that serve as.*
27f90 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66  * placeholders f
27fa0 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61  or values that a
27fb0 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  re [sqlite3_bind
27fc0 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a  _blob | bound].*
27fd0 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  * to the paramet
27fe0 65 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74  ers at a later t
27ff0 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  ime..**.** ^(Thi
28000 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c  s routine actual
28010 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69  ly returns the i
28020 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67  ndex of the larg
28030 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a  est (rightmost).
28040 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f  ** parameter. Fo
28050 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65  r all forms exce
28060 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69  pt ?NNN, this wi
28070 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f  ll correspond to
28080 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
28090 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74  f unique paramet
280a0 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74  ers.  If paramet
280b0 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20  ers of the ?NNN 
280c0 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a  form are used,.*
280d0 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67  * there may be g
280e0 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e  aps in the list.
280f0 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
28100 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
28110 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
28120 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
28130 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28140 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a  r_name()], and.*
28150 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
28160 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
28170 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
28180 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
28190 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
281a0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
281b0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
281c0 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
281d0 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a  st Parameter.**.
281e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
281f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
28200 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
28210 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
28220 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
28230 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
28240 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
28250 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
28260 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
28270 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
28280 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
28290 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
282a0 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
282b0 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
282c0 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
282d0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
282e0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
282f0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
28300 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
28310 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
28320 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
28330 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
28340 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
28350 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
28360 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
28370 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
28380 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
28390 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
283a0 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
283b0 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
283c0 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
283d0 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
283e0 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
283f0 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
28400 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
28410 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
28420 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
28430 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
28440 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
28450 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
28460 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
28470 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
28480 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
28490 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
284a0 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
284b0 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
284c0 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
284d0 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
284e0 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
284f0 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
28500 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
28510 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
28520 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
28530 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
28540 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
28550 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
28560 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
28570 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28580 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
28590 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
285a0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
285b0 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  dex()]..*/.SQLIT
285c0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
285d0 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   *sqlite3_bind_p
285e0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71  arameter_name(sq
285f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28600 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28610 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50  EF: Index Of A P
28620 61 72 61 6d 65 74 65 72 20 57 69 74 68 20 41 20  arameter With A 
28630 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a  Given Name.**.**
28640 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64   ^Return the ind
28650 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72  ex of an SQL par
28660 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69 74 73  ameter given its
28670 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20   name.  ^The.** 
28680 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65 74 75  index value retu
28690 72 6e 65 64 20 69 73 20 73 75 69 74 61 62 6c 65  rned is suitable
286a0 20 66 6f 72 20 75 73 65 20 61 73 20 74 68 65 20   for use as the 
286b0 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65  second.** parame
286c0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
286d0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
286e0 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a  3_bind()].  ^A z
286f0 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e  ero.** is return
28700 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e  ed if no matchin
28710 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 66  g parameter is f
28720 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61  ound.  ^The para
28730 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75  meter.** name mu
28740 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55  st be given in U
28750 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65  TF-8 even if the
28760 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
28770 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61  ent.** was prepa
28780 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20  red from UTF-16 
28790 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  text using [sqli
287a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
287b0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
287c0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
287d0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
287e0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
287f0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28800 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
28810 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
28820 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
28830 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
28840 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
28850 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28860 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74  index(sqlite3_st
28870 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  mt*, const char 
28880 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *zName);../*.** 
28890 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
288a0 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20  All Bindings On 
288b0 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
288c0 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74  ment.**.** ^Cont
288d0 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75  rary to the intu
288e0 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b  ition of many, [
288f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28900 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a   does not reset.
28910 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
28920 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64  bind_blob | bind
28930 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70  ings] on a [prep
28940 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
28950 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f  .** ^Use this ro
28960 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61  utine to reset a
28970 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65  ll host paramete
28980 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53  rs to NULL..*/.S
28990 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
289a0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
289b0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
289c0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
289d0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
289e0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
289f0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
28a00 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
28a10 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
28a20 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
28a30 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
28a40 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
28a50 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
28a60 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
28a70 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
28a80 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
28a90 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
28aa0 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
28ab0 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
28ac0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
28ad0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
28ae0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51  a_count()].*/.SQ
28af0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28b00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
28b10 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
28b20 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
28b30 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20  API3REF: Column 
28b40 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c  Names In A Resul
28b50 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t Set.**.** ^The
28b60 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
28b70 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69  rn the name assi
28b80 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74 69 63  gned to a partic
28b90 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  ular column.** i
28ba0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
28bb0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73   of a [SELECT] s
28bc0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20  tatement.  ^The 
28bd0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
28be0 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ame().** interfa
28bf0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
28c00 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
28c10 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
28c20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71  string.** and sq
28c30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
28c40 65 31 36 28 29 20 72 65 74 75 72 6e 73 20 61 20  e16() returns a 
28c50 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
28c60 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
28c70 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
28c80 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
28c90 65 74 65 72 20 69 73 20 74 68 65 20 5b 70 72 65  eter is the [pre
28ca0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
28cb0 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  .** that impleme
28cc0 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  nts the [SELECT]
28cd0 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65   statement. ^The
28ce0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
28cf0 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r is the.** colu
28d00 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65  mn number.  ^The
28d10 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
28d20 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a   is number 0..**
28d30 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65  .** ^The returne
28d40 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72  d string pointer
28d50 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20   is valid until 
28d60 65 69 74 68 65 72 20 74 68 65 20 5b 70 72 65 70  either the [prep
28d70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
28d80 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65 64 20  ** is destroyed 
28d90 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  by [sqlite3_fina
28da0 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c  lize()] or until
28db0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
28dc0 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a  s automatically.
28dd0 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20 62 79  ** reprepared by
28de0 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
28df0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
28e00 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63  ()] for a partic
28e10 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75  ular run.** or u
28e20 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61  ntil the next ca
28e30 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ll to.** sqlite3
28e40 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f  _column_name() o
28e50 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
28e60 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65  _name16() on the
28e70 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a   same column..**
28e80 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
28e90 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64  malloc() fails d
28ea0 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73  uring the proces
28eb0 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72  sing of either r
28ec0 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65  outine.** (for e
28ed0 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20  xample during a 
28ee0 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20  conversion from 
28ef0 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29  UTF-8 to UTF-16)
28f00 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20   then a.** NULL 
28f10 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72  pointer is retur
28f20 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
28f30 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74  name of a result
28f40 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76   column is the v
28f50 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41 53 22  alue of the "AS"
28f60 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74   clause for.** t
28f70 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74  hat column, if t
28f80 68 65 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c  here is an AS cl
28f90 61 75 73 65 2e 20 20 49 66 20 74 68 65 72 65 20  ause.  If there 
28fa0 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a  is no AS clause.
28fb0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65  ** then the name
28fc0 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69   of the column i
28fd0 73 20 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e  s unspecified an
28fe0 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f  d may change fro
28ff0 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65  m.** one release
29000 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68   of SQLite to th
29010 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54  e next..*/.SQLIT
29020 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
29030 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
29040 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
29050 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c  mt*, int N);.SQL
29060 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
29070 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
29080 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
29090 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
290a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
290b0 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
290c0 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
290d0 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  lt.**.** ^These 
290e0 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
290f0 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
29100 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
29110 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
29120 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
29130 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
29140 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
29150 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
29160 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
29170 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
29180 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
29190 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
291a0 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
291b0 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
291c0 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
291d0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
291e0 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
291f0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
29200 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
29210 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
29220 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
29230 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
29240 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
29250 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
29260 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
29270 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
29280 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
29290 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
292a0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
292b0 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
292c0 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
292d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
292e0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
292f0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
29300 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
29310 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
29320 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
29330 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
29340 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
29350 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
29360 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
29370 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
29380 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
29390 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
293a0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
293b0 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
293c0 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
293d0 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
293e0 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
293f0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
29400 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
29410 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
29420 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
29430 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
29440 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
29450 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
29460 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
29470 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
29480 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
29490 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
294a0 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
294b0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
294c0 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
294d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
294e0 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
294f0 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
29500 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
29510 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
29520 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
29530 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
29540 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
29550 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
29560 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
29570 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
29580 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
29590 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
295a0 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
295b0 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
295c0 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
295d0 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
295e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
295f0 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
29600 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
29610 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
29620 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
29630 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
29640 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
29650 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
29660 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
29670 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
29680 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
29690 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
296a0 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
296b0 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
296c0 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
296d0 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
296e0 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
296f0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
29700 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
29710 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
29720 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
29730 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
29740 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
29750 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
29760 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
29770 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
29780 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
29790 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
297a0 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
297b0 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
297c0 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
297d0 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
297e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
297f0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
29800 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
29810 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
29820 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
29830 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
29840 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
29850 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
29860 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
29870 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
29880 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
29890 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
298a0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
298b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
298c0 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
298d0 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
298e0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
298f0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
29900 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54  efined..*/.SQLIT
29910 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
29920 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
29930 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73  _database_name(s
29940 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
29950 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
29960 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
29970 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
29980 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
29990 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
299a0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
299b0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
299c0 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71  mn_table_name(sq
299d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
299e0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
299f0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
29a00 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61  _column_table_na
29a10 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
29a20 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
29a30 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
29a40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
29a50 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74  rigin_name(sqlit
29a60 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
29a70 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
29a80 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
29a90 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
29aa0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
29ab0 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
29ac0 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
29ad0 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
29ae0 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
29af0 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
29b00 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
29b10 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29b20 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
29b30 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
29b40 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
29b50 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
29b60 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
29b70 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
29b80 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
29b90 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
29ba0 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
29bb0 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
29bc0 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
29bd0 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
29be0 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
29bf0 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
29c00 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
29c10 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
29c20 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
29c30 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
29c40 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
29c50 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
29c60 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
29c70 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
29c80 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
29c90 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
29ca0 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
29cb0 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
29cc0 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
29cd0 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
29ce0 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
29cf0 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
29d00 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
29d10 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
29d20 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
29d30 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
29d40 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
29d50 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
29d60 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
29d70 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
29d80 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
29d90 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
29da0 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
29db0 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
29dc0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
29dd0 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
29de0 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
29df0 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
29e00 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
29e10 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
29e20 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
29e30 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
29e40 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
29e50 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
29e60 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
29e70 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
29e80 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
29e90 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
29ea0 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
29eb0 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
29ec0 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
29ed0 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
29ee0 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
29ef0 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
29f00 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
29f10 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
29f20 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
29f30 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
29f40 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  es..*/.SQLITE_AP
29f50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
29f60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
29f70 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
29f80 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
29f90 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
29fa0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29fb0 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74  decltype16(sqlit
29fc0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
29fd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29fe0 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20  Evaluate An SQL 
29ff0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20  Statement.**.** 
2a000 41 66 74 65 72 20 61 20 5b 70 72 65 70 61 72 65  After a [prepare
2a010 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73  d statement] has
2a020 20 62 65 65 6e 20 70 72 65 70 61 72 65 64 20 75   been prepared u
2a030 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b  sing either.** [
2a040 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2a050 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  v2()] or [sqlite
2a060 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2a070 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20  ] or one of the 
2a080 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
2a090 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72  aces [sqlite3_pr
2a0a0 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c  epare()] or [sql
2a0b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2a0c0 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ], this function
2a0d0 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  .** must be call
2a0e0 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  ed one or more t
2a0f0 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65  imes to evaluate
2a100 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a   the statement..
2a110 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c  **.** The detail
2a120 73 20 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f  s of the behavio
2a130 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  r of the sqlite3
2a140 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66 61 63  _step() interfac
2a150 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77  e depend.** on w
2a160 68 65 74 68 65 72 20 74 68 65 20 73 74 61 74 65  hether the state
2a170 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61 72 65  ment was prepare
2a180 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65  d using the newe
2a190 72 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  r "v2" interface
2a1a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2a1b0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
2a1c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a1d0 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f  6_v2()] or the o
2a1e0 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69  lder legacy.** i
2a1f0 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65  nterface [sqlite
2a200 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
2a210 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a220 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65  e16()].  The use
2a230 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22   of the.** new "
2a240 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
2a250 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
2a260 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
2a270 73 20 62 75 74 20 74 68 65 20 6c 65 67 61 63 79  s but the legacy
2a280 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69  .** interface wi
2a290 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62  ll continue to b
2a2a0 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a  e supported..**.
2a2b0 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63  ** ^In the legac
2a2c0 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
2a2d0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69   return value wi
2a2e0 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b 53 51  ll be either [SQ
2a2f0 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b  LITE_BUSY],.** [
2a300 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53  SQLITE_DONE], [S
2a310 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c  QLITE_ROW], [SQL
2a320 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b  ITE_ERROR], or [
2a330 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a  SQLITE_MISUSE]..
2a340 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22 76 32  ** ^With the "v2
2a350 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79  " interface, any
2a360 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72   of the other [r
2a370 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a  esult codes] or.
2a380 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73  ** [extended res
2a390 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74  ult codes] might
2a3a0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 20   be returned as 
2a3b0 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  well..**.** ^[SQ
2a3c0 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73  LITE_BUSY] means
2a3d0 20 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61   that the databa
2a3e0 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e  se engine was un
2a3f0 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20  able to acquire 
2a400 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
2a410 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74  locks it needs t
2a420 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e  o do its job.  ^
2a430 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2a440 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a   is a [COMMIT].*
2a450 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73  * or occurs outs
2a460 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63  ide of an explic
2a470 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
2a480 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74  then you can ret
2a490 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d  ry the.** statem
2a4a0 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73 74 61  ent.  If the sta
2a4b0 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20  tement is not a 
2a4c0 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63  [COMMIT] and occ
2a4d0 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a  urs within an.**
2a4e0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2a4f0 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73  ction then you s
2a500 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74  hould rollback t
2a510 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
2a520 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75  efore.** continu
2a530 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c  ing..**.** ^[SQL
2a540 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20  ITE_DONE] means 
2a550 74 68 61 74 20 74 68 65 20 73 74 61 74 65 6d 65  that the stateme
2a560 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  nt has finished 
2a570 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63  executing.** suc
2a580 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69  cessfully.  sqli
2a590 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c  te3_step() shoul
2a5a0 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20  d not be called 
2a5b0 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69  again on this vi
2a5c0 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
2a5d0 20 77 69 74 68 6f 75 74 20 66 69 72 73 74 20 63   without first c
2a5e0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2a5f0 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65  reset()] to rese
2a600 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a  t the virtual.**
2a610 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f   machine back to
2a620 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
2a630 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  te..**.** ^If th
2a640 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
2a650 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 20 72  being executed r
2a660 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c  eturns any data,
2a670 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   then [SQLITE_RO
2a680 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  W].** is returne
2a690 64 20 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65  d each time a ne
2a6a0 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73  w row of data is
2a6b0 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65   ready for proce
2a6c0 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20  ssing by the.** 
2a6d0 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75  caller. The valu
2a6e0 65 73 20 6d 61 79 20 62 65 20 61 63 63 65 73 73  es may be access
2a6f0 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f  ed using the [co
2a700 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63  lumn access func
2a710 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74  tions]..** sqlit
2a720 65 33 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c  e3_step() is cal
2a730 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74  led again to ret
2a740 72 69 65 76 65 20 74 68 65 20 6e 65 78 74 20 72  rieve the next r
2a750 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a  ow of data..**.*
2a760 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  * ^[SQLITE_ERROR
2a770 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72  ] means that a r
2a780 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73  un-time error (s
2a790 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61  uch as a constra
2a7a0 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e  int.** violation
2a7b0 29 20 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20  ) has occurred. 
2a7c0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2a7d0 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2a7e0 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a  lled again on.**
2a7f0 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e   the VM. More in
2a800 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65  formation may be
2a810 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e   found by callin
2a820 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  g [sqlite3_errms
2a830 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  g()]..** ^With t
2a840 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2a850 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63  ace, a more spec
2a860 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20  ific error code 
2a870 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (for example,.**
2a880 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
2a890 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48  PT], [SQLITE_SCH
2a8a0 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f  EMA], [SQLITE_CO
2a8b0 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66  RRUPT], and so f
2a8c0 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20  orth).** can be 
2a8d0 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c  obtained by call
2a8e0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2a8f0 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20  et()] on the.** 
2a900 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2a910 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22  ent].  ^In the "
2a920 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a  v2" interface,.*
2a930 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69  * the more speci
2a940 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69  fic error code i
2a950 73 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  s returned direc
2a960 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73  tly by sqlite3_s
2a970 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51  tep()..**.** [SQ
2a980 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61  LITE_MISUSE] mea
2a990 6e 73 20 74 68 61 74 20 74 68 65 20 74 68 69 73  ns that the this
2a9a0 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c   routine was cal
2a9b0 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74  led inappropriat
2a9c0 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20  ely..** Perhaps 
2a9d0 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e  it was called on
2a9e0 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2a9f0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
2aa00 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e  .** already been
2aa10 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2aa20 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20  ze | finalized] 
2aa30 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68  or on one that h
2aa40 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ad.** previously
2aa50 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2aa60 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c  E_ERROR] or [SQL
2aa70 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69  ITE_DONE].  Or i
2aa80 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68  t could.** be th
2aa90 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65 20  e case that the 
2aaa0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
2aab0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  nnection is bein
2aac0 67 20 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72  g used by two or
2aad0 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73  .** more threads
2aae0 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d   at the same mom
2aaf0 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a  ent in time..**.
2ab00 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69  ** For all versi
2ab10 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70  ons of SQLite up
2ab20 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e   to and includin
2ab30 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61  g 3.6.23.1, a ca
2ab40 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2ab50 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73 20 72  3_reset()] was r
2ab60 65 71 75 69 72 65 64 20 61 66 74 65 72 20 73 71  equired after sq
2ab70 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72 65 74  lite3_step() ret
2ab80 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a  urned anything.*
2ab90 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  * other than [SQ
2aba0 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65  LITE_ROW] before
2abb0 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20   any subsequent 
2abc0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a  invocation of.**
2abd0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2abe0 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73    Failure to res
2abf0 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64 20  et the prepared 
2ac00 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
2ac10 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2ac20 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75  et()] would resu
2ac30 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45  lt in an [SQLITE
2ac40 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20  _MISUSE] return 
2ac50 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  from.** sqlite3_
2ac60 73 74 65 70 28 29 2e 20 20 42 75 74 20 61 66 74  step().  But aft
2ac70 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32  er version 3.6.2
2ac80 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65  3.1, sqlite3_ste
2ac90 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c  p() began.** cal
2aca0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2acb0 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63  set()] automatic
2acc0 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72  ally in this cir
2acd0 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72  cumstance rather
2ace0 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69  .** than returni
2acf0 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ng [SQLITE_MISUS
2ad00 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74  E].  This is not
2ad10 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f   considered a co
2ad20 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62  mpatibility.** b
2ad30 72 65 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79  reak because any
2ad40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61   application tha
2ad50 74 20 65 76 65 72 20 72 65 63 65 69 76 65 73 20  t ever receives 
2ad60 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  an SQLITE_MISUSE
2ad70 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f   error.** is bro
2ad80 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f  ken by definitio
2ad90 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  n.  The [SQLITE_
2ada0 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20  OMIT_AUTORESET] 
2adb0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
2adc0 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ion.** can be us
2add0 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68  ed to restore th
2ade0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
2adf0 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66  r..**.** <b>Goof
2ae00 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72  y Interface Aler
2ae10 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65  t:</b> In the le
2ae20 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2ae30 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70  the sqlite3_step
2ae40 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73  ().** API always
2ae50 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72   returns a gener
2ae60 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b  ic error code, [
2ae70 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66  SQLITE_ERROR], f
2ae80 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20  ollowing any.** 
2ae90 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e  error other than
2aea0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61   [SQLITE_BUSY] a
2aeb0 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  nd [SQLITE_MISUS
2aec0 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61  E].  You must ca
2aed0 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  ll.** [sqlite3_r
2aee0 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69  eset()] or [sqli
2aef0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2af00 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
2af10 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73   one of the.** s
2af20 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2af30 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74 74 65  odes] that bette
2af40 72 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  r describes the 
2af50 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d  error..** We adm
2af60 69 74 20 74 68 61 74 20 74 68 69 73 20 69 73 20  it that this is 
2af70 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20  a goofy design. 
2af80 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73   The problem has
2af90 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77   been fixed.** w
2afa0 69 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74  ith the "v2" int
2afb0 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20  erface.  If you 
2afc0 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79  prepare all of y
2afd0 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  our SQL statemen
2afe0 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68  ts.** using eith
2aff0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
2b000 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
2b010 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2b020 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a  v2()] instead.**
2b030 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b   of the legacy [
2b040 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2b050 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2b060 70 72 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74  prepare16()] int
2b070 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e  erfaces,.** then
2b080 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66   the more specif
2b090 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ic [error codes]
2b0a0 20 61 72 65 20 72 65 74 75 72 6e 65 64 20 64 69   are returned di
2b0b0 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c  rectly.** by sql
2b0c0 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68  ite3_step().  Th
2b0d0 65 20 75 73 65 20 6f 66 20 74 68 65 20 22 76 32  e use of the "v2
2b0e0 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2b0f0 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53  ecommended..*/.S
2b100 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2b110 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74  lite3_step(sqlit
2b120 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2b130 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2b140 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2b150 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a   a result set.**
2b160 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2b170 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69  _data_count(P) i
2b180 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2b190 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2b1a0 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a  olumns in the.**
2b1b0 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20   current row of 
2b1c0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2b1d0 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  f [prepared stat
2b1e0 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66  ement] P..** ^If
2b1f0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2b200 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68  ent P does not h
2b210 61 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64  ave results read
2b220 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28  y to return.** (
2b230 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  via calls to the
2b240 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2b250 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63  _int | sqlite3_c
2b260 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a  olumn_*()] of.**
2b270 20 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65   interfaces) the
2b280 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  n sqlite3_data_c
2b290 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20  ount(P) returns 
2b2a0 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  0..** ^The sqlit
2b2b0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2b2c0 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65   routine also re
2b2d0 74 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20  turns 0 if P is 
2b2e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2b2f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b300 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
2b310 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
2b320 69 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  if the previous 
2b330 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2b340 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2b350 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f  urned [SQLITE_DO
2b360 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  NE].  ^The sqlit
2b370 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2b380 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  .** will return 
2b390 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76  non-zero if prev
2b3a0 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71  ious call to [sq
2b3b0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2b3c0 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49  eturned.** [SQLI
2b3d0 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20  TE_ROW], except 
2b3e0 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74  in the case of t
2b3f0 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65  he [PRAGMA incre
2b400 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a  mental_vacuum].*
2b410 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79  * where it alway
2b420 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73  s returns zero s
2b430 69 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f  ince each step o
2b440 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65  f that multi-ste
2b450 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75  p.** pragma retu
2b460 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66  rns 0 columns of
2b470 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   data..**.** See
2b480 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2b490 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a  column_count()].
2b4a0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2b4b0 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
2b4c0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2b4d0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2b4e0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
2b4f0 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
2b500 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
2b510 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
2b520 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69   ^(Every value i
2b530 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
2b540 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
2b550 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
2b560 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
2b570 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
2b580 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
2b590 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
2b5a0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2b5b0 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
2b5c0 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
2b5d0 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
2b5e0 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
2b5f0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
2b600 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
2b610 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
2b620 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2b630 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
2b640 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
2b650 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
2b660 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
2b670 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
2b680 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
2b690 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
2b6a0 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
2b6b0 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
2b6c0 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
2b6d0 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
2b6e0 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
2b6f0 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
2b700 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
2b710 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
2b720 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
2b730 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
2b740 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2b750 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
2b760 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
2b770 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
2b780 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
2b790 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
2b7a0 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
2b7b0 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
2b7c0 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
2b7d0 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
2b7e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b7f0 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
2b800 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45  om A Query.** KE
2b810 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
2b820 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2b830 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
2b840 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20  utines form the 
2b850 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74  "result set" int
2b860 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  erface..**.** ^T
2b870 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
2b880 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2b890 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
2b8a0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
2b8b0 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20  rrent.** result 
2b8c0 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
2b8d0 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20   ^In every case 
2b8e0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2b8f0 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
2b900 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
2b910 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2b920 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
2b930 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
2b940 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
2b950 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
2b960 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
2b970 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2b980 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
2b990 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
2b9a0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2b9b0 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2b9c0 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
2b9d0 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
2b9e0 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
2b9f0 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66  turned. ^The lef
2ba00 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
2ba10 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
2ba20 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
2ba30 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  ** ^The number o
2ba40 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2ba50 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64   result can be d
2ba60 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a  etermined using.
2ba70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2ba80 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a  mn_count()]..**.
2ba90 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
2baa0 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2bab0 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
2bac0 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
2bad0 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
2bae0 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
2baf0 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
2bb00 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2bb10 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
2bb20 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
2bb30 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
2bb40 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2bb50 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2bb60 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2bb70 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2bb80 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
2bb90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2bba0 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
2bbb0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
2bbc0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
2bbd0 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
2bbe0 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
2bbf0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2bc00 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
2bc10 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2bc20 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2bc30 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
2bc40 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2bc50 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
2bc60 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
2bc70 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2bc80 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
2bc90 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2bca0 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
2bcb0 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2bcc0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2bcd0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2bce0 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
2bcf0 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
2bd00 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
2bd10 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2bd20 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
2bd30 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
2bd40 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2bd50 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2bd60 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2bd70 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
2bd80 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
2bd90 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
2bda0 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
2bdb0 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
2bdc0 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
2bdd0 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
2bde0 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
2bdf0 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
2be00 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2be10 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
2be20 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
2be30 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
2be40 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
2be50 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
2be60 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2be70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2be80 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
2be90 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
2bea0 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
2beb0 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
2bec0 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
2bed0 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
2bee0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
2bef0 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
2bf00 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2bf10 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2bf20 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
2bf30 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
2bf40 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
2bf50 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
2bf60 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
2bf70 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
2bf80 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
2bf90 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
2bfa0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2bfb0 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2bfc0 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
2bfd0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2bfe0 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
2bff0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2c000 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2c010 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2c020 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2c030 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2c040 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
2c050 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2c060 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
2c070 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2c080 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
2c090 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2c0a0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2c0b0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2c0c0 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2c0d0 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2c0e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2c0f0 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2c100 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2c110 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2c120 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
2c130 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2c140 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2c150 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2c160 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
2c170 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
2c180 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
2c190 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2c1a0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2c1b0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
2c1c0 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
2c1d0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
2c1e0 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2c1f0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2c200 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2c210 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2c220 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2c230 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2c240 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2c250 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
2c260 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2c270 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2c280 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2c290 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2c2a0 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
2c2b0 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2c2c0 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2c2d0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2c2e0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2c2f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2c300 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
2c310 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2c320 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2c330 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2c340 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
2c350 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2c360 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2c370 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2c380 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2c390 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2c3a0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2c3b0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
2c3c0 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2c3d0 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
2c3e0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2c3f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2c400 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
2c410 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c420 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
2c430 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
2c440 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
2c450 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
2c460 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
2c470 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
2c480 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
2c490 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c4a0 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
2c4b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c4c0 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
2c4d0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
2c4e0 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
2c4f0 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
2c500 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2c510 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
2c520 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2c530 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2c540 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
2c550 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
2c560 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
2c570 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
2c580 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2c590 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
2c5a0 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
2c5b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2c5c0 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
2c5d0 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
2c5e0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
2c5f0 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  ** ^The object r
2c600 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2c610 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2c620 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
2c630 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2c640 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
2c650 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64    An unprotected
2c660 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2c670 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  bject.** may onl
2c680 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b  y be used with [
2c690 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2c6a0 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
2c6b0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2c6c0 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
2c6d0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2c6e0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2c6f0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2c700 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2c710 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
2c720 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
2c730 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
2c740 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
2c750 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
2c760 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
2c770 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2c780 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2c790 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2c7a0 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ()], then the be
2c7b0 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2c7c0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ned..**.** These
2c7d0 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
2c7e0 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
2c7f0 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
2c800 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a  ropriate.  ^For.
2c810 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
2c820 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
2c830 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
2c840 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
2c850 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
2c860 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
2c870 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
2c880 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
2c890 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
2c8a0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
2c8b0 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
2c8c0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
2c8d0 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
2c8e0 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
2c8f0 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
2c900 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2c910 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2c920 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2c930 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
2c940 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
2c950 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
2c960 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
2c970 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2c980 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
2c990 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
2c9a0 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
2c9b0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2c9c0 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
2c9d0 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
2c9e0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2c9f0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2ca00 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
2ca10 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2ca20 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2ca30 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2ca40 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
2ca50 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2ca60 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2ca70 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2ca80 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2ca90 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
2caa0 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
2cab0 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
2cac0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2cad0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2cae0 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
2caf0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2cb00 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2cb10 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
2cb20 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
2cb30 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2cb40 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2cb50 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
2cb60 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72  float to integer
2cb70 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2cb80 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
2cb90 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2cba0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2cbb0 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2cbc0 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2cbd0 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2cbe0 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54  Same as FLOAT->T
2cbf0 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
2cc00 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
2cc10 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65  TEGER   <td> Use
2cc20 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
2cc30 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2cc40 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2cc50 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   Use atof().** <
2cc60 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2cc70 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2cc80 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
2cc90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2cca0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2ccb0 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2ccc0 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
2ccd0 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
2cce0 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2ccf0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2cd00 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
2cd10 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29   then use atof()
2cd20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2cd30 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
2cd40 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
2cd50 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2cd60 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
2cd70 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2cd80 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54  quote>)^.**.** T
2cd90 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
2cda0 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
2cdb0 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
2cdc0 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
2cdd0 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
2cde0 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
2cdf0 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
2ce00 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2ce10 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
2ce20 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
2ce30 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
2ce40 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
2ce50 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
2ce60 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
2ce70 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
2ce80 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
2ce90 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
2cea0 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
2ceb0 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
2cec0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
2ced0 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
2cee0 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
2cef0 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
2cf00 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
2cf10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cf20 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
2cf30 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
2cf40 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
2cf50 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2cf60 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
2cf70 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
2cf80 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
2cf90 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
2cfa0 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
2cfb0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
2cfc0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
2cfd0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
2cfe0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2cff0 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
2d000 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2d010 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
2d020 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d030 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2d040 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
2d050 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
2d060 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
2d070 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
2d080 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
2d090 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2d0a0 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
2d0b0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2d0c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2d0d0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2d0e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2d0f0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2d100 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2d110 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2d120 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
2d130 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2d140 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2d150 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
2d160 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2d170 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2d180 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2d190 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
2d1a0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2d1b0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2d1c0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2d1d0 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
2d1e0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
2d1f0 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2d200 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2d210 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2d220 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2d230 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2d240 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2d250 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2d260 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2d270 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2d280 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2d290 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
2d2a0 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
2d2b0 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
2d2c0 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
2d2d0 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
2d2e0 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
2d2f0 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
2d300 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
2d310 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
2d320 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
2d330 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
2d340 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
2d350 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
2d360 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
2d370 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
2d380 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
2d390 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
2d3a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2d3b0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
2d3c0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
2d3d0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
2d3e0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2d3f0 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
2d400 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2d410 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2d420 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2d430 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2d440 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2d450 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2d460 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2d470 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d480 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
2d490 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2d4a0 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
2d4b0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2d4c0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
2d4d0 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
2d4e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2d4f0 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
2d500 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2d510 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2d520 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
2d530 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
2d540 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
2d550 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
2d560 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
2d570 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d580 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
2d590 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2d5a0 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
2d5b0 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
2d5c0 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
2d5d0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
2d5e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2d5f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2d600 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
2d610 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2d620 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2d630 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
2d640 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
2d650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2d660 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
2d670 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2d680 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
2d690 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
2d6a0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
2d6b0 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
2d6c0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
2d6d0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
2d6e0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
2d6f0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
2d700 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2d710 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2d720 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d730 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
2d740 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
2d750 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
2d760 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
2d770 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
2d780 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
2d790 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
2d7a0 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
2d7b0 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74  turned.** [sqlit
2d7c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2d7d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
2d7e0 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
2d7f0 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
2d800 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
2d810 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
2d820 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
2d830 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
2d840 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
2d850 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
2d860 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
2d870 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
2d880 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
2d890 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
2d8a0 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
2d8b0 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
2d8c0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
2d8d0 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
2d8e0 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
2d8f0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
2d900 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
2d910 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
2d920 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2d930 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ].)^.*/.SQLITE_A
2d940 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2d950 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2d960 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2d970 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2d980 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2d990 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d9a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d9b0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2d9c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2d9d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2d9e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2d9f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
2da00 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c  E_API double sql
2da10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62  ite3_column_doub
2da20 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
2da30 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
2da40 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2da50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73  te3_column_int(s
2da60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2da70 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
2da80 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  API sqlite3_int6
2da90 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  4 sqlite3_column
2daa0 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2dab0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2dac0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2dad0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
2dae0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2daf0 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  text(sqlite3_stm
2db00 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2db10 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2db20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2db30 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
2db40 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2db50 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2db60 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2db70 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
2db80 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2db90 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
2dba0 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c  lite3_value *sql
2dbb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2dbc0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2dbd0 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a   int iCol);../*.
2dbe0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 73  ** CAPI3REF: Des
2dbf0 74 72 6f 79 20 41 20 50 72 65 70 61 72 65 64 20  troy A Prepared 
2dc00 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
2dc10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2dc20 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66  te3_finalize() f
2dc30 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65  unction is calle
2dc40 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70  d to delete a [p
2dc50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2dc60 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  t]..** ^If the m
2dc70 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75  ost recent evalu
2dc80 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61  ation of the sta
2dc90 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72  tement encounter
2dca0 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  ed no errors.** 
2dcb0 6f 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d  or if the statem
2dcc0 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65  ent is never bee
2dcd0 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65  n evaluated, the
2dce0 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  n sqlite3_finali
2dcf0 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  ze() returns.** 
2dd00 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20  SQLITE_OK.  ^If 
2dd10 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2dd20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74  evaluation of st
2dd30 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64  atement S failed
2dd40 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  , then.** sqlite
2dd50 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65  3_finalize(S) re
2dd60 74 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70  turns the approp
2dd70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
2dd80 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  e] or.** [extend
2dd90 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  ed error code]..
2dda0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2ddb0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72  e3_finalize(S) r
2ddc0 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61  outine can be ca
2ddd0 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e  lled at any poin
2dde0 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20  t during.** the 
2ddf0 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70  life cycle of [p
2de00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2de10 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20  t] S:.** before 
2de20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65  statement S is e
2de30 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61  ver evaluated, a
2de40 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d  fter.** one or m
2de50 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ore calls to [sq
2de60 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20  lite3_reset()], 
2de70 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c  or after any cal
2de80 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  l.** to [sqlite3
2de90 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c  _step()] regardl
2dea0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
2deb0 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d  r not the statem
2dec0 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c  ent has.** compl
2ded0 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a  eted execution..
2dee0 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20  **.** ^Invoking 
2def0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2df00 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69  () on a NULL poi
2df10 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65  nter is a harmle
2df20 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20  ss no-op..**.** 
2df30 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
2df40 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76  must finalize ev
2df50 65 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74  ery [prepared st
2df60 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65  atement] in orde
2df70 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65  r to avoid.** re
2df80 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49  source leaks.  I
2df90 74 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20  t is a grievous 
2dfa0 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70  error for the ap
2dfb0 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79  plication to try
2dfc0 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65   to use.** a pre
2dfd0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2dfe0 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
2dff0 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e  n finalized.  An
2e000 79 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61  y use of a prepa
2e010 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  red.** statement
2e020 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
2e030 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e  en finalized can
2e040 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
2e050 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65  ined and.** unde
2e060 73 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72  sirable behavior
2e070 20 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c   such as segfaul
2e080 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72  ts and heap corr
2e090 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  uption..*/.SQLIT
2e0a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2e0b0 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74  3_finalize(sqlit
2e0c0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2e0d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e0e0 3a 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72  : Reset A Prepar
2e0f0 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2e100 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ect.**.** The sq
2e110 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75  lite3_reset() fu
2e120 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64  nction is called
2e130 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65   to reset a [pre
2e140 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e150 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20  .** object back 
2e160 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
2e170 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62  tate, ready to b
2e180 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a  e re-executed..*
2e190 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65  * ^Any SQL state
2e1a0 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74  ment variables t
2e1b0 68 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62  hat had values b
2e1c0 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69  ound to them usi
2e1d0 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ng.** the [sqlit
2e1e0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73  e3_bind_blob | s
2e1f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2e200 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69  API] retain thei
2e210 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65  r values..** Use
2e220 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f   [sqlite3_clear_
2e230 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72  bindings()] to r
2e240 65 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67  eset the binding
2e250 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  s..**.** ^The [s
2e260 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2e270 20 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74   interface reset
2e280 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
2e290 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20  statement] S.** 
2e2a0 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69  back to the begi
2e2b0 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f  nning of its pro
2e2c0 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  gram..**.** ^If 
2e2d0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2e2e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2e2f0 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
2e300 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2e310 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75  tatement] S retu
2e320 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
2e330 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ] or [SQLITE_DON
2e340 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71  E],.** or if [sq
2e350 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68  lite3_step(S)] h
2e360 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20  as never before 
2e370 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53  been called on S
2e380 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74  ,.** then [sqlit
2e390 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2e3a0 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
2e3b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2e3c0 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2e3d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2e3e0 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2e3f0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e400 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65  ment] S indicate
2e410 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e  d an error, then
2e420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2e430 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61  et(S)] returns a
2e440 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  n appropriate [e
2e450 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a  rror code]..**.*
2e460 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
2e470 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66  reset(S)] interf
2e480 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  ace does not cha
2e490 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a  nge the values.*
2e4a0 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65  * of any [sqlite
2e4b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64  3_bind_blob|bind
2e4c0 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72  ings] on the [pr
2e4d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e4e0 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ] S..*/.SQLITE_A
2e4f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72  PI int sqlite3_r
2e500 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  eset(sqlite3_stm
2e510 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2e520 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61  * CAPI3REF: Crea
2e530 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53  te Or Redefine S
2e540 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  QL Functions.** 
2e550 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74  KEYWORDS: {funct
2e560 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
2e570 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  tines}.** KEYWOR
2e580 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
2e590 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2e5a0 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52  ction}.** KEYWOR
2e5b0 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e  DS: {application
2e5c0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
2e5d0 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54  ctions}.**.** ^T
2e5e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28  hese functions (
2e5f0 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f  collectively kno
2e600 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20  wn as "function 
2e610 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2e620 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20  s").** are used 
2e630 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74  to add SQL funct
2e640 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
2e650 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e  es or to redefin
2e660 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a  e the behavior.*
2e670 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51  * of existing SQ
2e680 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61  L functions or a
2e690 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20  ggregates.  The 
2e6a0 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73  only differences
2e6b0 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73   between.** thes
2e6c0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74  e routines are t
2e6d0 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  he text encoding
2e6e0 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a   expected for.**
2e6f0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
2e700 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20  meter (the name 
2e710 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  of the function 
2e720 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a  being created).*
2e730 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e  * and the presen
2e740 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66  ce or absence of
2e750 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61   a destructor ca
2e760 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68  llback for.** th
2e770 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
2e780 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  ta pointer..**.*
2e790 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
2e7a0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64  ameter is the [d
2e7b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e7c0 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65  on] to which the
2e7d0 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e   SQL.** function
2e7e0 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e   is to be added.
2e7f0 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61    ^If an applica
2e800 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74  tion uses more t
2e810 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65  han one database
2e820 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  .** connection t
2e830 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  hen application-
2e840 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2e850 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64  tions must be ad
2e860 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64  ded.** to each d
2e870 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e880 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a  on separately..*
2e890 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  *.** ^The second
2e8a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
2e8b0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51  e name of the SQ
2e8c0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  L function to be
2e8d0 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72   created or.** r
2e8e0 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20  edefined.  ^The 
2e8f0 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61  length of the na
2e900 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f  me is limited to
2e910 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20   255 bytes in a 
2e920 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65  UTF-8.** represe
2e930 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69  ntation, exclusi
2e940 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74  ve of the zero-t
2e950 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74  erminator.  ^Not
2e960 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a  e that the name.
2e970 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20  ** length limit 
2e980 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65  is in UTF-8 byte
2e990 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s, not character
2e9a0 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74  s nor UTF-16 byt
2e9b0 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74  es.  .** ^Any at
2e9c0 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20  tempt to create 
2e9d0 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  a function with 
2e9e0 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a  a longer name.**
2e9f0 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20   will result in 
2ea00 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2ea10 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a  being returned..
2ea20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
2ea30 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67   parameter (nArg
2ea40 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62  ).** is the numb
2ea50 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
2ea60 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e  that the SQL fun
2ea70 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2ea80 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66  egate takes. ^If
2ea90 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
2eaa0 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20  is -1, then the 
2eab0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
2eac0 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79  ** aggregate may
2ead0 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72   take any number
2eae0 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65   of arguments be
2eaf0 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20  tween 0 and the 
2eb00 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20  limit.** set by 
2eb10 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28  [sqlite3_limit](
2eb20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
2eb30 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49  NCTION_ARG]).  I
2eb40 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
2eb50 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73  arameter is less
2eb60 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61   than -1 or grea
2eb70 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65  ter than 127 the
2eb80 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2eb90 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s.** undefined..
2eba0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74  **.** ^The fourt
2ebb0 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65  h parameter, eTe
2ebc0 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73  xtRep, specifies
2ebd0 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45   what.** [SQLITE
2ebe0 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63  _UTF8 | text enc
2ebf0 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20  oding] this SQL 
2ec00 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73  function prefers
2ec10 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61   for.** its para
2ec20 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79 20 53  meters.  Every S
2ec30 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  QL function impl
2ec40 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
2ec50 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a  be able to work.
2ec60 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55  ** with UTF-8, U
2ec70 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d  TF-16le, or UTF-
2ec80 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20  16be.  But some 
2ec90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2eca0 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65  may be.** more e
2ecb0 66 66 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e  fficient with on
2ecc0 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20  e encoding than 
2ecd0 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70  another.  ^An ap
2ece0 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a  plication may.**
2ecf0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
2ed00 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2ed10 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65  ) or sqlite3_cre
2ed20 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
2ed30 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d   multiple.** tim
2ed40 65 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  es with the same
2ed50 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69   function but wi
2ed60 74 68 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c  th different val
2ed70 75 65 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e  ues of eTextRep.
2ed80 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70  .** ^When multip
2ed90 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2eda0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
2edb0 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69  unction are avai
2edc0 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a  lable, SQLite.**
2edd0 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f   will pick the o
2ede0 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73  ne that involves
2edf0 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e   the least amoun
2ee00 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72  t of data conver
2ee10 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72  sion..** If ther
2ee20 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67  e is only a sing
2ee30 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2ee40 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74  n which does not
2ee50 20 63 61 72 65 20 77 68 61 74 20 74 65 78 74 0a   care what text.
2ee60 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75  ** encoding is u
2ee70 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f  sed, then the fo
2ee80 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68  urth argument sh
2ee90 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f  ould be [SQLITE_
2eea0 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ANY]..**.** ^(Th
2eeb0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
2eec0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
2eed0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
2eee0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2eef0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
2ef00 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
2ef10 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
2ef20 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
2ef30 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
2ef40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
2ef50 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65  h, seventh and e
2ef60 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73  ighth parameters
2ef70 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
2ef80 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
2ef90 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
2efa0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
2efb0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
2efc0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2efd0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2efe0 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
2eff0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
2f000 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
2f010 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
2f020 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
2f030 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
2f040 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  rs must be passe
2f050 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
2f060 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
2f070 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
2f080 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
2f090 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
2f0a0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2f0b0 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
2f0c0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70  Final and NULL p
2f0d0 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70  ointer must be p
2f0e0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
2f0f0 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
2f100 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
2f110 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
2f120 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
2f130 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c  pointers for all
2f140 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
2f150 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
2f160 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
2f170 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2f180 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f190 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
2f1a0 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
2f1b0 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
2f1c0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
2f1d0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
2f1e0 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
2f1f0 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
2f200 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
2f210 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
2f220 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
2f230 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
2f240 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
2f250 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
2f260 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
2f270 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
2f280 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
2f290 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
2f2a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2f2b0 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
2f2c0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
2f2d0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
2f2e0 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
2f2f0 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
2f300 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
2f310 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
2f320 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
2f330 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
2f340 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
2f350 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
2f360 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
2f370 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2f380 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f390 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
2f3a0 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
2f3b0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
2f3c0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
2f3d0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2f3e0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
2f3f0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
2f400 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
2f410 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
2f420 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
2f430 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
2f440 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
2f450 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
2f460 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
2f470 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
2f480 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
2f490 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
2f4a0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
2f4b0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
2f4c0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
2f4d0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2f4e0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
2f4f0 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
2f500 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
2f510 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
2f520 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
2f530 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
2f540 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
2f550 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
2f560 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
2f570 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
2f580 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
2f590 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
2f5a0 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
2f5b0 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
2f5c0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
2f5d0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2f5e0 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
2f5f0 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
2f600 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
2f610 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
2f620 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
2f630 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
2f640 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
2f650 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
2f660 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
2f670 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
2f680 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
2f690 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
2f6a0 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
2f6b0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
2f6c0 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
2f6d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2f6e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
2f6f0 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
2f700 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2f710 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
2f720 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
2f730 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
2f740 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
2f750 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
2f760 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
2f770 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2f780 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
2f790 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
2f7a0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2f7b0 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
2f7c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
2f7d0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
2f7e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2f7f0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2f800 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  n(.  sqlite3 *db
2f810 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
2f820 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2f830 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2f840 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2f850 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2f860 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2f870 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2f880 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2f890 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2f8a0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f8b0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2f8c0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2f8d0 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2f8e0 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c  context*).);.SQL
2f8f0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2f900 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2f910 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
2f920 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f   *db,.  const vo
2f930 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  id *zFunctionNam
2f940 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2f950 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2f960 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2f970 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2f980 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2f990 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2f9a0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2f9b0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2f9c0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2f9d0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2f9e0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2f9f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b  te3_context*).);
2fa00 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2fa10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2fa20 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71  unction_v2(.  sq
2fa30 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e  lite3 *db,.  con
2fa40 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69  st char *zFuncti
2fa50 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41  onName,.  int nA
2fa60 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  rg,.  int eTextR
2fa70 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70  ep,.  void *pApp
2fa80 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63  ,.  void (*xFunc
2fa90 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2faa0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
2fab0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
2fac0 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33  (*xStep)(sqlite3
2fad0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2fae0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2faf0 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29    void (*xFinal)
2fb00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2fb10 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73  *),.  void(*xDes
2fb20 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a  troy)(void*).);.
2fb30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2fb40 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a   Text Encodings.
2fb50 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
2fb60 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65  tant define inte
2fb70 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72  ger codes that r
2fb80 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72  epresent the var
2fb90 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63  ious.** text enc
2fba0 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64  odings supported
2fbb0 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23   by SQLite..*/.#
2fbc0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2fbd0 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23  F8           1.#
2fbe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2fbf0 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23  F16LE        2.#
2fc00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2fc10 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23  F16BE        3.#
2fc20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2fc30 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20  F16          4  
2fc40 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20    /* Use native 
2fc50 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64  byte order */.#d
2fc60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59  efine SQLITE_ANY
2fc70 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20              5   
2fc80 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
2fc90 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79  te_function only
2fca0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
2fcb0 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
2fcc0 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    8    /* sqlite
2fcd0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
2fce0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a  on only */../*.*
2fcf0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 70 72  * CAPI3REF: Depr
2fd00 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73  ecated Functions
2fd10 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a  .** DEPRECATED.*
2fd20 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
2fd30 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63  ions are [deprec
2fd40 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72  ated].  In order
2fd50 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20   to maintain.** 
2fd60 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
2fd70 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64  ibility with old
2fd80 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66  er code, these f
2fd90 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75  unctions continu
2fda0 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70  e .** to be supp
2fdb0 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c  orted.  However,
2fdc0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
2fdd0 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a  s should avoid.*
2fde0 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  * the use of the
2fdf0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  se functions.  T
2fe00 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65  o help encourage
2fe10 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64   people to avoid
2fe20 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20  .** using these 
2fe30 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72  functions, we ar
2fe40 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74  e not going to t
2fe50 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65  ell you what the
2fe60 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  y do..*/.#ifndef
2fe70 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50   SQLITE_OMIT_DEP
2fe80 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41  RECATED.SQLITE_A
2fe90 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
2fea0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2feb0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
2fec0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2fed0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  *);.SQLITE_API S
2fee0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2fef0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70   int sqlite3_exp
2ff00 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d  ired(sqlite3_stm
2ff10 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
2ff20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2ff30 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72  D int sqlite3_tr
2ff40 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28  ansfer_bindings(
2ff50 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73  sqlite3_stmt*, s
2ff60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
2ff70 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
2ff80 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2ff90 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72  sqlite3_global_r
2ffa0 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51  ecover(void);.SQ
2ffb0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
2ffc0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
2ffd0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
2ffe0 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
2fff0 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
30000 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
30010 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c  qlite3_memory_al
30020 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64  arm(void(*)(void
30030 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c  *,sqlite3_int64,
30040 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74  int),void*,sqlit
30050 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69  e3_int64);.#endi
30060 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
30070 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c  F: Obtaining SQL
30080 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65   Function Parame
30090 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a  ter Values.**.**
300a0 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20   The C-language 
300b0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
300c0 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  f SQL functions 
300d0 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75  and aggregates u
300e0 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20  ses.** this set 
300f0 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75  of interface rou
30100 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20  tines to access 
30110 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61  the parameter va
30120 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66  lues on.** the f
30130 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
30140 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  gate..**.** The 
30150 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61  xFunc (for scala
30160 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20  r functions) or 
30170 78 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65  xStep (for aggre
30180 67 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72  gates) parameter
30190 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33  s.** to [sqlite3
301a0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
301b0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
301c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
301d0 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20  16()].** define 
301e0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69  callbacks that i
301f0 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c  mplement the SQL
30200 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
30210 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68  ggregates..** Th
30220 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
30230 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63  to these callbac
30240 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  ks is an array o
30250 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a  f pointers to.**
30260 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
30270 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30280 74 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e  ts.  There is on
30290 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
302a0 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20  ] object for.** 
302b0 65 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74  each parameter t
302c0 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  o the SQL functi
302d0 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  on.  These routi
302e0 6e 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a  nes are used to.
302f0 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65  ** extract value
30300 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  s from the [sqli
30310 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30320 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ts..**.** These 
30330 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e  routines work on
30340 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74  ly with [protect
30350 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30360 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e  ] objects..** An
30370 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  y attempt to use
30380 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
30390 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74  on an [unprotect
303a0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
303b0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75  ].** object resu
303c0 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
303d0 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
303e0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
303f0 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20   work just like 
30400 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
30410 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  g [column access
30420 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65   functions].** e
30430 78 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73  xcept that  thes
30440 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20  e routines take 
30450 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63  a single [protec
30460 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30470 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69  e] object.** poi
30480 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20  nter instead of 
30490 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  a [sqlite3_stmt*
304a0 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e  ] pointer and an
304b0 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20   integer column 
304c0 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  number..**.** ^T
304d0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
304e0 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66  _text16() interf
304f0 61 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55  ace extracts a U
30500 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20  TF-16 string.** 
30510 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
30520 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20  te-order of the 
30530 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e  host machine.  ^
30540 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  The.** sqlite3_v
30550 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20  alue_text16be() 
30560 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  and sqlite3_valu
30570 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74  e_text16le() int
30580 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61  erfaces.** extra
30590 63 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ct UTF-16 string
305a0 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20  s as big-endian 
305b0 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61  and little-endia
305c0 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  n respectively..
305d0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
305e0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
305f0 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61  c_type() interfa
30600 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61  ce attempts to a
30610 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20  pply.** numeric 
30620 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20  affinity to the 
30630 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61  value.  This mea
30640 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d  ns that an attem
30650 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f  pt is.** made to
30660 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c   convert the val
30670 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  ue to an integer
30680 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69   or floating poi
30690 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20  nt.  If.** such 
306a0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  a conversion is 
306b0 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74  possible without
306c0 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61   loss of informa
306d0 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a  tion (in other.*
306e0 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20  * words, if the 
306f0 76 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e  value is a strin
30700 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b  g that looks lik
30710 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74  e a number).** t
30720 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69  hen the conversi
30730 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e  on is performed.
30740 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63    Otherwise no c
30750 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
30760 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ..** The [SQLITE
30770 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74  _INTEGER | datat
30780 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65  ype] after conve
30790 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65  rsion is returne
307a0 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73  d.)^.**.** Pleas
307b0 65 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72  e pay particular
307c0 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68   attention to th
307d0 65 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20  e fact that the 
307e0 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64  pointer returned
307f0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
30800 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c  3_value_blob()],
30810 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30820 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  text()], or.** [
30830 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
30840 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69  xt16()] can be i
30850 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20  nvalidated by a 
30860 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
30870 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  to.** [sqlite3_v
30880 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b  alue_bytes()], [
30890 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
308a0 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74  tes16()], [sqlit
308b0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
308c0 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ,.** or [sqlite3
308d0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
308e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
308f0 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63  utines must be c
30900 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
30910 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a  ame thread as.**
30920 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
30930 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20  n that supplied 
30940 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
30950 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e  ue*] parameters.
30960 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
30970 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
30980 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71  e3_value_blob(sq
30990 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
309a0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
309b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
309c0 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
309d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
309e0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
309f0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
30a00 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
30a10 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  API double sqlit
30a20 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
30a30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
30a40 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
30a50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
30a60 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
30a70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
30a80 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
30a90 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28  te3_value_int64(
30aa0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
30ab0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
30ac0 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20  t unsigned char 
30ad0 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
30ae0 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ext(sqlite3_valu
30af0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
30b00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
30b10 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
30b20 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
30b30 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
30b40 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
30b50 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
30b60 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
30b70 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
30b80 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
30b90 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73  value_text16be(s
30ba0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
30bb0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
30bc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
30bd0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
30be0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
30bf0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
30c00 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c  numeric_type(sql
30c10 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f  ite3_value*);../
30c20 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
30c30 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65 20  btain Aggregate 
30c40 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
30c50 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74  .**.** Implement
30c60 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67  ations of aggreg
30c70 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
30c80 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f  s use this.** ro
30c90 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74  utine to allocat
30ca0 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f  e memory for sto
30cb0 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74 65  ring their state
30cc0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
30cd0 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69  st time the sqli
30ce0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
30cf0 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69  ntext(C,N) routi
30d00 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a  ne is called .**
30d10 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
30d20 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  r aggregate func
30d30 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  tion, SQLite.** 
30d40 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d  allocates N of m
30d50 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75  emory, zeroes ou
30d60 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61  t that memory, a
30d70 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  nd returns a poi
30d80 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e  nter.** to the n
30d90 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73  ew memory. ^On s
30da0 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71  econd and subseq
30db0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  uent calls to.**
30dc0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
30dd0 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72  te_context() for
30de0 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67   the same aggreg
30df0 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73  ate function ins
30e00 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61  tance,.** the sa
30e10 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65 74  me buffer is ret
30e20 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f  urned.  Sqlite3_
30e30 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
30e40 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a  t() is normally.
30e50 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66  ** called once f
30e60 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69  or each invocati
30e70 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70 20  on of the xStep 
30e80 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65  callback and the
30e90 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69  n one.** last ti
30ea0 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e  me when the xFin
30eb0 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  al callback is i
30ec0 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20  nvoked.  ^(When 
30ed0 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a  no rows match.**
30ee0 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71 75   an aggregate qu
30ef0 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28 29  ery, the xStep()
30f00 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   callback of the
30f10 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
30f20 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ion.** implement
30f30 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63  ation is never c
30f40 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c  alled and xFinal
30f50 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61  () is called exa
30f60 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e  ctly once..** In
30f70 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71   those cases, sq
30f80 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
30f90 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20  context() might 
30fa0 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68  be called for th
30fb0 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20  e.** first time 
30fc0 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e  from within xFin
30fd0 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  al().)^.**.** ^T
30fe0 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  he sqlite3_aggre
30ff0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
31000 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
31010 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
31020 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73   if N is.** less
31030 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
31040 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
31050 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65  emory allocate e
31060 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a  rror occurs..**.
31070 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20  ** ^(The amount 
31080 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74  of space allocat
31090 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67  ed by sqlite3_ag
310a0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
310b0 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72  C,N) is.** deter
310c0 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70  mined by the N p
310d0 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73  arameter on firs
310e0 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c  t successful cal
310f0 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65  l.  Changing the
31100 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69  .** value of N i
31110 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  n subsequent cal
31120 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67  l to sqlite3_agg
31130 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
31140 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73   within.** the s
31150 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
31160 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20  nction instance 
31170 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20  will not resize 
31180 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  the memory.** al
31190 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a  location.)^.**.*
311a0 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61  * ^SQLite automa
311b0 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68  tically frees th
311c0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
311d0 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65  ed by .** sqlite
311e0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
311f0 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20 61  ext() when the a
31200 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20 63  ggregate query c
31210 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20  oncludes..**.** 
31220 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
31230 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f  ter must be a co
31240 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71  py of the.** [sq
31250 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20  lite3_context | 
31260 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e  SQL function con
31270 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74 68  text] that is th
31280 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
31290 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65  r.** to the xSte
312a0 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  p or xFinal call
312b0 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61  back routine tha
312c0 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65  t implements the
312d0 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75   aggregate.** fu
312e0 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
312f0 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
31300 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
31310 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
31320 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
31330 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
31340 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
31350 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
31360 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67  void *sqlite3_ag
31370 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31380 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31390 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a  , int nBytes);..
313a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
313b0 55 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75  User Data For Fu
313c0 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
313d0 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  he sqlite3_user_
313e0 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
313f0 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20   returns a copy 
31400 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65  of.** the pointe
31410 72 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70  r that was the p
31420 55 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74  UserData paramet
31430 65 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61  er (the 5th para
31440 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
31450 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
31460 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
31470 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
31480 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
31490 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
314a0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
314b0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
314c0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
314d0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
314e0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
314f0 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
31500 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
31510 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
31520 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
31530 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
31540 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
31550 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
31560 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
31570 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31580 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
31590 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
315a0 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e  nnection For Fun
315b0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
315c0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e sqlite3_contex
315d0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e  t_db_handle() in
315e0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
315f0 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
31600 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
31610 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
31620 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70  tion] (the 1st p
31630 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
31640 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
31650 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
31660 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
31670 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
31680 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
31690 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
316a0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
316b0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
316c0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f  ned function..*/
316d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
316e0 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
316f0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
31700 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
31710 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
31720 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
31730 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
31740 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
31750 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
31760 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
31770 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
31780 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
31790 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
317a0 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
317b0 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
317c0 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
317d0 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
317e0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
317f0 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
31800 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
31810 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
31820 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
31830 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
31840 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
31850 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
31860 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
31870 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
31880 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
31890 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
318a0 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
318b0 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
318c0 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
318d0 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
318e0 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
318f0 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
31900 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
31910 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
31920 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
31930 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
31940 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
31950 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
31960 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
31970 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
31980 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
31990 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
319a0 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
319b0 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
319c0 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
319d0 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
319e0 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
319f0 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
31a00 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
31a10 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
31a20 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
31a30 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
31a40 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
31a50 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
31a60 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
31a70 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
31a80 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
31a90 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
31aa0 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
31ab0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
31ac0 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f  function. ^If no
31ad0 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
31ae0 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20  en ever.** been 
31af0 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20  set for the Nth 
31b00 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
31b10 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
31b20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
31b30 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  g.** function pa
31b40 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e  rameter has chan
31b50 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
31b60 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
31b70 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
31b80 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72  _get_auxdata() r
31b90 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
31ba0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
31bb0 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
31bc0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
31bd0 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
31be0 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
31bf0 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
31c00 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
31c10 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
31c20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
31c30 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
31c40 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
31c50 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e  tion.  Subsequen
31c60 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
31c70 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
31c80 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e  a() might return
31c90 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69   this data, if i
31ca0 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65  t has.** not bee
31cb0 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20  n destroyed..** 
31cc0 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  ^If it is not NU
31cd0 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
31ce0 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
31cf0 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
31d00 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
31d10 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
31d20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
31d30 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
31d40 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
31d50 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
31d60 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
31d70 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
31d80 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
31d90 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
31da0 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
31db0 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
31dc0 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
31dd0 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
31de0 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
31df0 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
31e00 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
31e10 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
31e20 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f  ny time.  ^The o
31e30 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73  nly guarantee is
31e40 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73   that.** the des
31e50 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
31e60 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
31e70 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72  e metadata is dr
31e80 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  opped..**.** ^(I
31e90 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
31ea0 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
31eb0 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
31ec0 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
31ed0 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
31ee0 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
31ef0 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
31f00 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
31f10 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
31f20 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e  nd [parameters].
31f30 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
31f40 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
31f50 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
31f60 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
31f70 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
31f80 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
31f90 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
31fa0 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
31fb0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _get_auxdata(sql
31fc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
31fd0 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt N);.SQLITE_AP
31fe0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73  I void sqlite3_s
31ff0 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
32000 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
32010 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20   N, void*, void 
32020 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f  (*)(void*));.../
32030 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
32040 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e  onstants Definin
32050 67 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75  g Special Destru
32060 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a  ctor Behavior.**
32070 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70  .** These are sp
32080 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72  ecial values for
32090 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
320a0 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69  that is passed i
320b0 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61  n as the.** fina
320c0 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f  l argument to ro
320d0 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c  utines like [sql
320e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
320f0 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65  ()].  ^If the de
32100 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75  structor.** argu
32110 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53  ment is SQLITE_S
32120 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20  TATIC, it means 
32130 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
32140 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73   pointer is cons
32150 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c  tant.** and will
32160 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20   never change.  
32170 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  It does not need
32180 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64   to be destroyed
32190 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54  .  ^The.** SQLIT
321a0 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75  E_TRANSIENT valu
321b0 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  e means that the
321c0 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69   content will li
321d0 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a  kely change in.*
321e0 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72  * the near futur
321f0 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74  e and that SQLit
32200 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74  e should make it
32210 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f  s own private co
32220 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e  py of.** the con
32230 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75  tent before retu
32240 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  rning..**.** The
32250 20 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65   typedef is nece
32260 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72  ssary to work ar
32270 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e  ound problems in
32280 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20   certain.** C++ 
32290 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20  compilers.  See 
322a0 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f  ticket #2191..*/
322b0 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
322c0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
322d0 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b  or_type)(void*);
322e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
322f0 53 54 41 54 49 43 20 20 20 20 20 20 28 28 73 71  STATIC      ((sq
32300 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
32310 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65  _type)0).#define
32320 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e   SQLITE_TRANSIEN
32330 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65  T   ((sqlite3_de
32340 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31  structor_type)-1
32350 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
32360 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65 20 52  F: Setting The R
32370 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20  esult Of An SQL 
32380 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54  Function.**.** T
32390 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
323a0 65 20 75 73 65 64 20 62 79 20 74 68 65 20 78 46  e used by the xF
323b0 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  unc or xFinal ca
323c0 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20  llbacks that.** 
323d0 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75  implement SQL fu
323e0 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
323f0 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20  egates.  See.** 
32400 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32410 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
32420 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32430 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
32440 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
32450 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
32460 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
32470 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63  ns work very muc
32480 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61  h like the [para
32490 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66  meter binding] f
324a0 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63  amily of.** func
324b0 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69  tions used to bi
324c0 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73  nd values to hos
324d0 74 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20  t parameters in 
324e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
324f0 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f  nts..** Refer to
32500 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65   the [SQL parame
32510 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  ter] documentati
32520 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  on for additiona
32530 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
32540 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32550 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20  3_result_blob() 
32560 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
32570 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
32580 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
32590 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
325a0 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42  n to be the BLOB
325b0 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69   whose content i
325c0 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20  s pointed.** to 
325d0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  by the second pa
325e0 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63  rameter and whic
325f0 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e  h is N bytes lon
32600 67 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  g where N is the
32610 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
32620 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
32630 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a  sqlite3_result_z
32640 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  eroblob() interf
32650 61 63 65 73 20 73 65 74 20 74 68 65 20 72 65 73  aces set the res
32660 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
32670 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32680 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
32690 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69   a BLOB containi
326a0 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62  ng all zero.** b
326b0 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73  ytes and N bytes
326c0 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20   in size, where 
326d0 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  N is the value o
326e0 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  f the 2nd parame
326f0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
32700 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
32710 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  ouble() interfac
32720 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
32730 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
32740 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32750 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
32760 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  a floating point
32770 20 76 61 6c 75 65 20 73 70 65 63 69 66 69 65 64   value specified
32780 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61  .** by its 2nd a
32790 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
327a0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
327b0 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
327c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
327d0 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e  ror16() function
327e0 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69  s.** cause the i
327f0 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66  mplemented SQL f
32800 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77  unction to throw
32810 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a   an exception..*
32820 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
32830 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65  he string pointe
32840 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32  d to by the.** 2
32850 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  nd parameter of 
32860 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32870 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65  rror() or sqlite
32880 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
32890 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78  ().** as the tex
328a0 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65  t of an error me
328b0 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20  ssage.  ^SQLite 
328c0 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 65  interprets the e
328d0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
328e0 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
328f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32900 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51  () as UTF-8. ^SQ
32910 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65  Lite.** interpre
32920 74 73 20 74 68 65 20 73 74 72 69 6e 67 20 66 72  ts the string fr
32930 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
32940 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73 20 55  t_error16() as U
32950 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a  TF-16 in native.
32960 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20  ** byte order.  
32970 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
32980 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
32990 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
329a0 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
329b0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
329c0 20 69 73 20 6e 65 67 61 74 69 76 65 20 74 68 65   is negative the
329d0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61  n SQLite takes a
329e0 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
329f0 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20  essage all text 
32a00 75 70 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  up through the f
32a10 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
32a20 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
32a30 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
32a40 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
32a50 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20  t_error() or.** 
32a60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32a70 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d  rror16() is non-
32a80 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
32a90 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61 74 20  Lite takes that 
32aa0 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e  many.** bytes (n
32ab0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 66  ot characters) f
32ac0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
32ad0 6d 65 74 65 72 20 61 73 20 74 68 65 20 65 72 72  meter as the err
32ae0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e  or message..** ^
32af0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
32b00 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73  lt_error() and s
32b10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32b20 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69  ror16().** routi
32b30 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61  nes make a priva
32b40 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65  te copy of the e
32b50 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78  rror message tex
32b60 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79  t before.** they
32b70 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c   return.  Hence,
32b80 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e   the calling fun
32b90 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f  ction can deallo
32ba0 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66  cate or.** modif
32bb0 79 20 74 68 65 20 74 65 78 74 20 61 66 74 65 72  y the text after
32bc0 20 74 68 65 79 20 72 65 74 75 72 6e 20 77 69 74   they return wit
32bd0 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54  hout harm..** ^T
32be0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32bf0 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66  t_error_code() f
32c00 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20  unction changes 
32c10 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a  the error code.*
32c20 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 53 51  * returned by SQ
32c30 4c 69 74 65 20 61 73 20 61 20 72 65 73 75 6c 74  Lite as a result
32c40 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20   of an error in 
32c50 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79  a function.  ^By
32c60 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65   default,.** the
32c70 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53   error code is S
32c80 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41  QLITE_ERROR.  ^A
32c90 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
32ca0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
32cb0 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
32cc0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32cd0 65 72 72 6f 72 31 36 28 29 20 72 65 73 65 74 73  error16() resets
32ce0 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20   the error code 
32cf0 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e  to SQLITE_ERROR.
32d00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32d10 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
32d20 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65 72 66  _toobig() interf
32d30 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
32d40 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
32d50 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
32d60 67 20 74 68 61 74 20 61 20 73 74 72 69 6e 67 20  g that a string 
32d70 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c  or BLOB is too l
32d80 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65 6e 74  ong to represent
32d90 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32da0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32db0 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66  r_nomem() interf
32dc0 61 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74  ace causes SQLit
32dd0 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a  e to throw an.**
32de0 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74 69 6e   error indicatin
32df0 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20  g that a memory 
32e00 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65  allocation faile
32e10 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
32e20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
32e30 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
32e40 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  s the return val
32e50 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70  ue.** of the app
32e60 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
32e70 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
32e80 74 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65  the 32-bit signe
32e90 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c  d integer.** val
32ea0 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20  ue given in the 
32eb0 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
32ec0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
32ed0 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74  sult_int64() int
32ee0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
32ef0 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
32f00 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
32f10 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32f20 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34  ion to be the 64
32f30 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
32f40 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76  ger.** value giv
32f50 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72  en in the 2nd ar
32f60 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  gument..**.** ^T
32f70 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32f80 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61  t_null() interfa
32f90 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
32fa0 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
32fb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
32fc0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
32fd0 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  to be NULL..**.*
32fe0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32ff0 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71  esult_text(), sq
33000 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33010 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  t16(),.** sqlite
33020 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
33030 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  e(), and sqlite3
33040 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65  _result_text16be
33050 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
33060 20 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20   set the return 
33070 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70  value of the app
33080 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33090 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a   function to be.
330a0 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67  ** a text string
330b0 20 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73   which is repres
330c0 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20  ented as UTF-8, 
330d0 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79  UTF-16 native by
330e0 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46  te order,.** UTF
330f0 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61  -16 little endia
33100 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67  n, or UTF-16 big
33110 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74   endian, respect
33120 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ively..** ^SQLit
33130 65 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74  e takes the text
33140 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65   result from the
33150 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f   application fro
33160 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72  m.** the 2nd par
33170 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71  ameter of the sq
33180 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33190 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a  t* interfaces..*
331a0 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61  * ^If the 3rd pa
331b0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
331c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
331d0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a  xt* interfaces.*
331e0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
331f0 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
33200 20 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f   result text fro
33210 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
33220 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74  ter.** through t
33230 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68  he first zero ch
33240 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  aracter..** ^If 
33250 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
33260 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
33270 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
33280 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e  terfaces.** is n
33290 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
332a0 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20  n as many bytes 
332b0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
332c0 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20   of the text.** 
332d0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
332e0 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
332f0 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65  are taken as the
33300 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33310 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ined.** function
33320 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65   result.  If the
33330 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 69   3rd parameter i
33340 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
33350 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20  then it.** must 
33360 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
33370 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69  et into the stri
33380 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c  ng where the NUL
33390 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c   terminator woul
333a0 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74  d.** appear if t
333b0 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
333c0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  NUL terminated. 
333d0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
333e0 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20  acters occur.** 
333f0 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20 61 74  in the string at
33400 20 61 20 62 79 74 65 20 6f 66 66 73 65 74 20 74   a byte offset t
33410 68 61 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  hat is less than
33420 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
33430 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  e 3rd.** paramet
33440 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  er, then the res
33450 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69  ulting string wi
33460 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64  ll contain embed
33470 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65  ded NULs and the
33480 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78  .** result of ex
33490 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74  pressions operat
334a0 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77  ing on strings w
334b0 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ith embedded NUL
334c0 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  s is undefined..
334d0 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
334e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
334f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33500 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
33510 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
33520 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e  sult_blob is a n
33530 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c  on-NULL pointer,
33540 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c   then SQLite cal
33550 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74  ls that.** funct
33560 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73 74 72  ion as the destr
33570 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78  uctor on the tex
33580 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
33590 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20   when it has.** 
335a0 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74  finished using t
335b0 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e  hat result..** ^
335c0 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
335d0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
335e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
335f0 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74   interfaces or t
33600 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  o.** sqlite3_res
33610 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20  ult_blob is the 
33620 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74  special constant
33630 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20   SQLITE_STATIC, 
33640 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61  then SQLite.** a
33650 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 20  ssumes that the 
33660 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
33670 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61  ult is in consta
33680 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  nt space and doe
33690 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68  s not.** copy th
336a0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
336b0 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63   parameter nor c
336c0 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72  all a destructor
336d0 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a   on the content.
336e0 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73 20 66  ** when it has f
336f0 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68  inished using th
33700 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49  at result..** ^I
33710 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  f the 4th parame
33720 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
33730 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
33740 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72  interfaces.** or
33750 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33760 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
33770 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
33780 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a  ITE_TRANSIENT.**
33790 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b   then SQLite mak
337a0 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  es a copy of the
337b0 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61   result into spa
337c0 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ce obtained from
337d0 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
337e0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f  3_malloc()] befo
337f0 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a  re it returns..*
33800 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
33810 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
33820 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
33830 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
33840 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33850 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
33860 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74  n to be a copy t
33870 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  he.** [unprotect
33880 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
33890 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  ] object specifi
338a0 65 64 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  ed by the 2nd pa
338b0 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a  rameter.  ^The.*
338c0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
338d0 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
338e0 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20  ce makes a copy 
338f0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
33900 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61  value].** so tha
33910 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  t the [sqlite3_v
33920 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65 64 20  alue] specified 
33930 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
33940 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a   may change or.*
33950 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  * be deallocated
33960 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72   after sqlite3_r
33970 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65  esult_value() re
33980 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61  turns without ha
33990 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65  rm..** ^A [prote
339a0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
339b0 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61  ue] object may a
339c0 6c 77 61 79 73 20 62 65 20 75 73 65 64 20 77 68  lways be used wh
339d0 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f  ere an.** [unpro
339e0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
339f0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20  alue] object is 
33a00 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74  required, so eit
33a10 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b  her.** kind of [
33a20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
33a30 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75 73 65  bject can be use
33a40 64 20 77 69 74 68 20 74 68 69 73 20 69 6e 74 65  d with this inte
33a50 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  rface..**.** If 
33a60 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
33a70 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77  re called from w
33a80 69 74 68 69 6e 20 74 68 65 20 64 69 66 66 65 72  ithin the differ
33a90 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68  ent thread.** th
33aa0 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61  an the one conta
33ab0 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63  ining the applic
33ac0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33ad0 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65  nction that rece
33ae0 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  ived.** the [sql
33af0 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f  ite3_context] po
33b00 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c  inter, the resul
33b10 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
33b20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
33b30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33b40 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  ult_blob(sqlite3
33b50 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
33b60 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69   void*, int, voi
33b70 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
33b80 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
33b90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
33ba0 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ble(sqlite3_cont
33bb0 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53  ext*, double);.S
33bc0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
33bd0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33be0 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ror(sqlite3_cont
33bf0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
33c00 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
33c10 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
33c20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
33c30 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33c40 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
33c50 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
33c60 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33c70 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
33c80 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33c90 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
33ca0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33cb0 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
33cc0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
33cd0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
33ce0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33cf0 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69  _error_code(sqli
33d00 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
33d10 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
33d20 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33d30 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63  lt_int(sqlite3_c
33d40 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53  ontext*, int);.S
33d50 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
33d60 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
33d70 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t64(sqlite3_cont
33d80 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ext*, sqlite3_in
33d90 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
33da0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
33db0 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65  sult_null(sqlite
33dc0 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c  3_context*);.SQL
33dd0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
33de0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33df0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33e00 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
33e10 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
33e20 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
33e30 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
33e40 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69  sult_text16(sqli
33e50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
33e60 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
33e70 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
33e80 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
33e90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33ea0 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
33eb0 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
33ec0 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64   void*, int,void
33ed0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.SQL
33ee0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
33ef0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33f00 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  16be(sqlite3_con
33f10 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
33f20 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28  d*, int,void(*)(
33f30 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
33f40 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
33f50 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71  _result_value(sq
33f60 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
33f70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
33f80 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
33f90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33fa0 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33  zeroblob(sqlite3
33fb0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e  _context*, int n
33fc0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33fd0 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43  EF: Define New C
33fe0 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63  ollating Sequenc
33ff0 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  es.**.** ^These 
34000 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72  functions add, r
34010 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79  emove, or modify
34020 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61   a [collation] a
34030 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74  ssociated.** wit
34040 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
34050 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
34060 69 66 69 65 64 20 61 73 20 74 68 65 20 66 69 72  ified as the fir
34070 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
34080 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
34090 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73  the collation is
340a0 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a   a UTF-8 string.
340b0 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  ** for sqlite3_c
340c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
340d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72  ) and sqlite3_cr
340e0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
340f0 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46  2().** and a UTF
34100 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
34110 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
34120 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61  for sqlite3_crea
34130 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
34140 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20  ..** ^Collation 
34150 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61  names that compa
34160 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69  re equal accordi
34170 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ng to [sqlite3_s
34180 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a  trnicmp()] are.*
34190 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20  * considered to 
341a0 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  be the same name
341b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68  ..**.** ^(The th
341c0 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54  ird argument (eT
341d0 65 78 74 52 65 70 29 20 6d 75 73 74 20 62 65 20  extRep) must be 
341e0 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74  one of the const
341f0 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ants:.** <ul>.**
34200 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
34210 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  F8],.** <li> [SQ
34220 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a  LITE_UTF16LE],.*
34230 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55  * <li> [SQLITE_U
34240 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  TF16BE],.** <li>
34250 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c   [SQLITE_UTF16],
34260 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c   or.** <li> [SQL
34270 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
34280 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  D]..** </ul>)^.*
34290 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65 70 20  * ^The eTextRep 
342a0 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69  argument determi
342b0 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  nes the encoding
342c0 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61 73 73   of strings pass
342d0 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c  ed.** to the col
342e0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
342f0 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62  callback, xCallb
34300 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ack..** ^The [SQ
34310 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20  LITE_UTF16] and 
34320 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
34330 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f  IGNED] values fo
34340 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f  r eTextRep.** fo
34350 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62  rce strings to b
34360 65 20 55 54 46 31 36 20 77 69 74 68 20 6e 61 74  e UTF16 with nat
34370 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
34380 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
34390 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
343a0 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74 52 65  alue for eTextRe
343b0 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73  p forces strings
343c0 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20   to begin.** on 
343d0 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61 64 64  an even byte add
343e0 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ress..**.** ^The
343f0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
34400 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70  , pArg, is an ap
34410 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
34420 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20 70  ointer that is p
34430 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68  assed.** through
34440 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
34450 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f  gument to the co
34460 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
34470 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
34480 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75   ^The fifth argu
34490 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c  ment, xCallback,
344a0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
344b0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
344c0 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c  unction..** ^Mul
344d0 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20  tiple collating 
344e0 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65  functions can be
344f0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
34500 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
34510 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66  but.** with diff
34520 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 70  erent eTextRep p
34530 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51  arameters and SQ
34540 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68  Lite will use wh
34550 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74  ichever.** funct
34560 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74 68 65  ion requires the
34570 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
34580 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61   data transforma
34590 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  tion..** ^If the
345a0 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d   xCallback argum
345b0 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e  ent is NULL then
345c0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
345d0 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65  unction is.** de
345e0 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c  leted.  ^When al
345f0 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  l collating func
34600 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65  tions having the
34610 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64   same name are d
34620 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20  eleted,.** that 
34630 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20  collation is no 
34640 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a  longer usable..*
34650 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74  *.** ^The collat
34660 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
34670 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
34680 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20   with a copy of 
34690 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70  the pArg .** app
346a0 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
346b0 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68 20 74  inter and with t
346c0 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68  wo strings in th
346d0 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69  e encoding speci
346e0 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65  fied.** by the e
346f0 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
34700 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  .  The collating
34710 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72   function must r
34720 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65  eturn an.** inte
34730 67 65 72 20 74 68 61 74 20 69 73 20 6e 65 67 61  ger that is nega
34740 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70  tive, zero, or p
34750 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68  ositive.** if th
34760 65 20 66 69 72 73 74 20 73 74 72 69 6e 67 20 69  e first string i
34770 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75  s less than, equ
34780 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65  al to, or greate
34790 72 20 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e  r than the secon
347a0 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  d,.** respective
347b0 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67  ly.  A collating
347c0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61   function must a
347d0 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74 68 65  lways return the
347e0 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20   same answer.** 
347f0 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69  given the same i
34800 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f  nputs.  If two o
34810 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67  r more collating
34820 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72   functions are r
34830 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20  egistered.** to 
34840 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69  the same collati
34850 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64  on name (using d
34860 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
34870 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61  p values) then a
34880 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20  ll.** must give 
34890 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e  an equivalent an
348a0 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65  swer when invoke
348b0 64 20 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e  d with equivalen
348c0 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68  t strings..** Th
348d0 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
348e0 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74  tion must obey t
348f0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f  he following pro
34900 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a  perties for all.
34910 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c  ** strings A, B,
34920 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f   and C:.**.** <o
34930 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  l>.** <li> If A=
34940 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a  =B then B==A..**
34950 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e   <li> If A==B an
34960 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43  d B==C then A==C
34970 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c  ..** <li> If A&l
34980 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e  t;B THEN B&gt;A.
34990 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74  .** <li> If A&lt
349a0 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68  ;B and B&lt;C th
349b0 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f  en A&lt;C..** </
349c0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63  ol>.**.** If a c
349d0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
349e0 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74  n fails any of t
349f0 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61  he above constra
34a00 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a  ints and that.**
34a10 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34a20 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74 65 72  ion is  register
34a30 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65  ed and used, the
34a40 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
34a50 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75  f SQLite.** is u
34a60 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
34a70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65  ^The sqlite3_cre
34a80 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32  ate_collation_v2
34a90 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  () works like sq
34aa0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34ab0 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68  lation().** with
34ac0 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68   the addition th
34ad0 61 74 20 74 68 65 20 78 44 65 73 74 72 6f 79 20  at the xDestroy 
34ae0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
34af0 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e  ked on pArg when
34b00 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  .** the collatin
34b10 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  g function is de
34b20 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  leted..** ^Colla
34b30 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61  ting functions a
34b40 72 65 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  re deleted when 
34b50 74 68 65 79 20 61 72 65 20 6f 76 65 72 72 69 64  they are overrid
34b60 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20  den by later.** 
34b70 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c  calls to the col
34b80 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  lation creation 
34b90 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65  functions or whe
34ba0 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  n the.** [databa
34bb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
34bc0 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b  s closed using [
34bd0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
34be0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65  ..**.** ^The xDe
34bf0 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69  stroy callback i
34c00 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c  s <u>not</u> cal
34c10 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73  led if the .** s
34c20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
34c30 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e  llation_v2() fun
34c40 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70  ction fails.  Ap
34c50 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
34c60 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
34c70 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
34c80 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e  on_v2() with a n
34c90 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79  on-NULL xDestroy
34ca0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
34cb0 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72   .** check the r
34cc0 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64  eturn code and d
34cd0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70  ispose of the ap
34ce0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
34cf0 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65  ointer.** themse
34d00 6c 76 65 73 20 72 61 74 68 65 72 20 74 68 61 6e  lves rather than
34d10 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74   expecting SQLit
34d20 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69  e to deal with i
34d30 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54  t for them..** T
34d40 68 69 73 20 69 73 20 64 69 66 66 65 72 65 6e 74  his is different
34d50 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65   from every othe
34d60 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
34d70 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69  ce.  The inconsi
34d80 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e  stency .** is un
34d90 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20 63 61  fortunate but ca
34da0 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
34db0 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
34dc0 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63   backwards .** c
34dd0 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
34de0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b  .** See also:  [
34df0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
34e00 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20  n_needed()] and 
34e10 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69  [sqlite3_collati
34e20 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a  on_needed16()]..
34e30 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
34e40 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
34e50 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71  _collation(.  sq
34e60 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
34e70 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20   char *zName, . 
34e80 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
34e90 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
34ea0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
34eb0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
34ec0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
34ed0 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  oid*).);.SQLITE_
34ee0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34ef0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34f00 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  _v2(.  sqlite3*,
34f10 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a   .  const char *
34f20 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54  zName, .  int eT
34f30 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20  extRep, .  void 
34f40 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43  *pArg,.  int(*xC
34f50 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e  ompare)(void*,in
34f60 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e  t,const void*,in
34f70 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a  t,const void*),.
34f80 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79    void(*xDestroy
34f90 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49  )(void*).);.SQLI
34fa0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
34fb0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34fc0 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33  ion16(.  sqlite3
34fd0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  *, .  const void
34fe0 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65   *zName,.  int e
34ff0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
35000 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
35010 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
35020 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
35030 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a  nt,const void*).
35040 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35050 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65  EF: Collation Ne
35060 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  eded Callbacks.*
35070 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68  *.** ^To avoid h
35080 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65  aving to registe
35090 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20  r all collation 
350a0 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65  sequences before
350b0 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63   a database.** c
350c0 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73 69  an be used, a si
350d0 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ngle callback fu
350e0 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65  nction may be re
350f0 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74 68  gistered with th
35100 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
35110 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62 65  onnection] to be
35120 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
35130 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20 63  r an undefined c
35140 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75  ollation.** sequ
35150 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65 64  ence is required
35160 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
35170 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67 69  function is regi
35180 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68 65  stered using the
35190 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
351a0 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49 2c  on_needed() API,
351b0 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 70  .** then it is p
351c0 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73 20  assed the names 
351d0 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c  of undefined col
351e0 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
351f0 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20 65   as strings.** e
35200 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38 2e  ncoded in UTF-8.
35210 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c   ^If sqlite3_col
35220 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
35230 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74 68  ) is used,.** th
35240 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73 73  e names are pass
35250 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
35260 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20 62  machine native b
35270 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 41  yte order..** ^A
35280 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72 20   call to either 
35290 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63 65  function replace
352a0 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20 63  s the existing c
352b0 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64 20  ollation-needed 
352c0 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  callback..**.** 
352d0 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  ^(When the callb
352e0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ack is invoked, 
352f0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
35300 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20 63  nt passed is a c
35310 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 65  opy.** of the se
35320 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
35330 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
35340 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a 2a  on_needed() or.*
35350 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  * sqlite3_collat
35360 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e 20  ion_needed16(). 
35370 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
35380 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74 61  ment is the data
35390 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
353a0 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  on.  The third a
353b0 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20 6f  rgument is one o
353c0 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  f [SQLITE_UTF8],
353d0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
353e0 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  ],.** or [SQLITE
353f0 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69 63  _UTF16LE], indic
35400 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20 64  ating the most d
35410 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f 66  esirable form of
35420 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a   the collation.*
35430 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63 74  * sequence funct
35440 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20 54  ion required.  T
35450 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
35460 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
35470 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69 72  of the.** requir
35480 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
35490 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  uence.)^.**.** T
354a0 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
354b0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67 69  tion should regi
354c0 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65 64  ster the desired
354d0 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e 67   collation using
354e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  .** [sqlite3_cre
354f0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 5d  ate_collation()]
35500 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
35510 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 5d  e_collation16()]
35520 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
35530 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
35540 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  n_v2()]..*/.SQLI
35550 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
35560 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
35570 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
35580 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
35590 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
355a0 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
355b0 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
355c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
355d0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
355e0 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
355f0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
35600 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
35610 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
35620 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
35630 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66  oid*).);..#ifdef
35640 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45   SQLITE_HAS_CODE
35650 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  C./*.** Specify 
35660 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
35670 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
35680 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
35690 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
356a0 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
356b0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
356c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
356d0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
356e0 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
356f0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
35700 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
35710 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
35720 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
35730 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
35740 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
35750 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
35760 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
35770 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
35780 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
35790 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
357a0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
357b0 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
357c0 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
357d0 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
357e0 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
357f0 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
35800 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
35810 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
35820 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
35830 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
35840 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
35850 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
35860 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
35870 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
35880 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
35890 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
358a0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
358b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
358c0 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
358d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
358e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
358f0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
35900 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
35910 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
35920 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
35930 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
35940 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
35950 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
35960 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
35970 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
35980 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
35990 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
359a0 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
359b0 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45   work..*/.SQLITE
359c0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
359d0 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a  3_activate_see(.
359e0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
359f0 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
35a00 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
35a10 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
35a20 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  if..#ifdef SQLIT
35a30 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f  E_ENABLE_CEROD./
35a40 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
35a50 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
35a60 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61  for a CEROD data
35a70 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
35a80 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
35a90 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72  e of the CEROD r
35aa0 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
35ab0 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  k..*/.SQLITE_API
35ac0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63   void sqlite3_ac
35ad0 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20  tivate_cerod(.  
35ae0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73  const char *zPas
35af0 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f  sPhrase        /
35b00 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72  * Activation phr
35b10 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66  ase */.);.#endif
35b20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35b30 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74  : Suspend Execut
35b40 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20  ion For A Short 
35b50 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  Time.**.** The s
35b60 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66  qlite3_sleep() f
35b70 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74  unction causes t
35b80 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61  he current threa
35b90 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65  d to suspend exe
35ba0 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74  cution.** for at
35bb0 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20   least a number 
35bc0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
35bd0 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73  specified in its
35be0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
35bf0 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69  * If the operati
35c00 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e  ng system does n
35c10 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70  ot support sleep
35c20 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a   requests with.*
35c30 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69  * millisecond ti
35c40 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74  me resolution, t
35c50 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c  hen the time wil
35c60 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20  l be rounded up 
35c70 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73  to.** the neares
35c80 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75  t second. The nu
35c90 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
35ca0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63  onds of sleep ac
35cb0 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73  tually.** reques
35cc0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65  ted from the ope
35cd0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73  rating system is
35ce0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
35cf0 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65   ^SQLite impleme
35d00 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61  nts this interfa
35d10 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68  ce by calling th
35d20 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65  e xSleep().** me
35d30 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
35d40 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
35d50 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68  ] object.  If th
35d60 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
35d70 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61  d.** of the defa
35d80 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69  ult VFS is not i
35d90 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65  mplemented corre
35da0 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70  ctly, or not imp
35db0 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61  lemented at.** a
35dc0 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ll, then the beh
35dd0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
35de0 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76  _sleep() may dev
35df0 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65  iate from the de
35e00 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20  scription.** in 
35e10 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72  the previous par
35e20 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c 49  agraphs..*/.SQLI
35e30 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
35e40 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a  e3_sleep(int);..
35e50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
35e60 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64  Name Of The Fold
35e70 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f  er Holding Tempo
35e80 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  rary Files.**.**
35e90 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61   ^(If this globa
35ea0 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
35eb0 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
35ec0 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
35ed0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
35ee0 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
35ef0 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
35f00 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20  n all temporary 
35f10 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64  files.** created
35f20 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20   by SQLite when 
35f30 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e  using a built-in
35f40 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
35f50 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  VFS].** will be 
35f60 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64  placed in that d
35f70 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66  irectory.)^  ^If
35f80 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
35f90 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
35fa0 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ter, then SQLite
35fb0 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72   performs a sear
35fc0 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70  ch for an approp
35fd0 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  riate.** tempora
35fe0 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72  ry file director
35ff0 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20 6e  y..**.** It is n
36000 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
36010 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
36020 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65 20  ariable in more 
36030 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72 65  than one.** thre
36040 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20 49  ad at a time.  I
36050 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
36060 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
36070 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
36080 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65 20   if a [database 
36090 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
360a0 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68 65  eing used at the
360b0 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61 20   same time in a 
360c0 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72 65  separate.** thre
360d0 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e 74  ad..** It is int
360e0 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73 20  ended that this 
360f0 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74 20  variable be set 
36100 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74 20  once.** as part 
36110 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  of process initi
36120 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62 65  alization and be
36130 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65 20  fore any SQLite 
36140 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f 75  interface.** rou
36150 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e 20  tines have been 
36160 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74 20  called and that 
36170 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72 65  this variable re
36180 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a 2a  main unchanged.*
36190 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a 2a  * thereafter..**
361a0 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f 73  .** ^The [temp_s
361b0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
361c0 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69 66  ragma] may modif
361d0 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
361e0 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74 20  and cause.** it 
361f0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
36200 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
36210 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
36220 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72 65  ].  ^Furthermore
36230 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f 73  ,.** the [temp_s
36240 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
36250 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61 73  ragma] always as
36260 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20 73  sumes that any s
36270 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74 68  tring.** that th
36280 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69 6e  is variable poin
36290 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69 6e  ts to is held in
362a0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
362b0 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74   from .** [sqlit
362c0 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20 74  e3_malloc] and t
362d0 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61 74  he pragma may at
362e0 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74 68  tempt to free th
362f0 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73 69  at memory.** usi
36300 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
36310 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66 20  ]..** Hence, if 
36320 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 73  this variable is
36330 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63 74   modified direct
36340 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73 68  ly, either it sh
36350 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65 20  ould be.** made 
36360 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f 20  NULL or made to 
36370 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20  point to memory 
36380 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
36390 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a 2a  qlite3_malloc].*
363a0 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75 73  * or else the us
363b0 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f 73  e of the [temp_s
363c0 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
363d0 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62 65  ragma] should be
363e0 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   avoided..**.** 
363f0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
36400 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73  ws Runtime users
36410 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f  :</b>  The tempo
36420 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d  rary directory m
36430 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72  ust be set.** pr
36440 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 5b  ior to calling [
36450 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f 72  sqlite3_open] or
36460 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
36470 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  2].  Otherwise, 
36480 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75  various.** featu
36490 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65  res that require
364a0 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70   the use of temp
364b0 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20  orary files may 
364c0 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20 61  fail.  Here is a
364d0 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66 20  n.** example of 
364e0 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20 75  how to do this u
364f0 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74 68  sing C++ with th
36500 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  e Windows Runtim
36510 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  e:.**.** <blockq
36520 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c 50  uote><pre>.** LP
36530 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57 69  CWSTR zPath = Wi
36540 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a 3a  ndows::Storage::
36550 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61 3a  ApplicationData:
36560 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26 6e  :Current->.** &n
36570 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72 61  bsp;     Tempora
36580 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d 3e  ryFolder->Path->
36590 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72 20  Data();.** char 
365a0 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41 58  zPathBuf&#91;MAX
365b0 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b 0a  _PATH + 1&#93;;.
365c0 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68 42  ** memset(zPathB
365d0 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a 50  uf, 0, sizeof(zP
365e0 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69 64  athBuf));.** Wid
365f0 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74 65  eCharToMultiByte
36600 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50 61  (CP_UTF8, 0, zPa
36610 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75 66  th, -1, zPathBuf
36620 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42 75  , sizeof(zPathBu
36630 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20  f),.** &nbsp;   
36640 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a 2a    NULL, NULL);.*
36650 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64  * sqlite3_temp_d
36660 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69 74  irectory = sqlit
36670 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22 2c  e3_mprintf("%s",
36680 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20 3c   zPathBuf);.** <
36690 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
366a0 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e>.*/.SQLITE_API
366b0 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63   SQLITE_EXTERN c
366c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
366d0 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
366e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
366f0 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
36700 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61 73   Holding Databas
36710 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  e Files.**.** ^(
36720 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
36730 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
36740 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
36750 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
36760 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
36770 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
36780 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
36790 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ll database file
367a0 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 77  s.** specified w
367b0 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70  ith a relative p
367c0 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65 61  athname and crea
367d0 74 65 64 20 6f 72 20 61 63 63 65 73 73 65 64 20  ted or accessed 
367e0 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68 65  by.** SQLite whe
367f0 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
36800 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c 69  in windows [sqli
36810 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20 77  te3_vfs | VFS] w
36820 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a 2a  ill be assumed.*
36830 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76 65  * to be relative
36840 20 74 6f 20 74 68 61 74 20 64 69 72 65 63 74 6f   to that directo
36850 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20 76  ry.)^ ^If this v
36860 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c  ariable is a NUL
36870 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74 68  L.** pointer, th
36880 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
36890 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61 62  s that all datab
368a0 61 73 65 20 66 69 6c 65 73 20 73 70 65 63 69 66  ase files specif
368b0 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72 65  ied.** with a re
368c0 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65 20  lative pathname 
368d0 61 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f 20  are relative to 
368e0 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65  the current dire
368f0 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68 65  ctory.** for the
36900 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79 20   process.  Only 
36910 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
36920 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68 69  makes use of thi
36930 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72 69  s global.** vari
36940 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e 6f  able; it is igno
36950 72 65 64 20 62 79 20 74 68 65 20 75 6e 69 78 20  red by the unix 
36960 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67  VFS..**.** Chang
36970 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f 66  ing the value of
36980 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 77   this variable w
36990 68 69 6c 65 20 61 20 64 61 74 61 62 61 73 65 20  hile a database 
369a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a 2a  connection is.**
369b0 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c 74   open can result
369c0 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64 61   in a corrupt da
369d0 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74  tabase..**.** It
369e0 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
369f0 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
36a00 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
36a10 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
36a20 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
36a30 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
36a40 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
36a50 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
36a60 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
36a70 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36a80 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
36a90 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
36aa0 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
36ab0 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
36ac0 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
36ad0 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
36ae0 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
36af0 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
36b00 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
36b10 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
36b20 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
36b30 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
36b40 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
36b50 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
36b60 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
36b70 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
36b80 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 64  r..**.** ^The [d
36b90 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  ata_store_direct
36ba0 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
36bb0 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
36bc0 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
36bd0 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
36be0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
36bf0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
36c00 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
36c10 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 64  rmore,.** the [d
36c20 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  ata_store_direct
36c30 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
36c40 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
36c50 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
36c60 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
36c70 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
36c80 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
36c90 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
36ca0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
36cb0 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
36cc0 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
36cd0 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
36ce0 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
36cf0 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
36d00 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
36d10 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
36d20 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
36d30 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
36d40 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
36d50 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
36d60 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
36d70 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
36d80 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
36d90 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  he use of the [d
36da0 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  ata_store_direct
36db0 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
36dc0 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
36dd0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  /.SQLITE_API SQL
36de0 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72 20  ITE_EXTERN char 
36df0 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 64 69  *sqlite3_data_di
36e00 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a 20  rectory;../*.** 
36e10 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20 46  CAPI3REF: Test F
36e20 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20 4d  or Auto-Commit M
36e30 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ode.** KEYWORDS:
36e40 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   {autocommit mod
36e50 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e}.**.** ^The sq
36e60 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f  lite3_get_autoco
36e70 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63 65  mmit() interface
36e80 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
36e90 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66 20  o or.** zero if 
36ea0 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62 61  the given databa
36eb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
36ec0 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61 75   or is not in au
36ed0 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a 2a  tocommit mode,.*
36ee0 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
36ef0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
36f00 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61 75  e is on by defau
36f10 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d 6d  lt..** ^Autocomm
36f20 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61 62  it mode is disab
36f30 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e 5d  led by a [BEGIN]
36f40 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
36f50 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 20  Autocommit mode 
36f60 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62 79  is re-enabled by
36f70 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20 5b   a [COMMIT] or [
36f80 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a 2a  ROLLBACK]..**.**
36f90 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e 64   If certain kind
36fa0 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63 75  s of errors occu
36fb0 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e 74  r on a statement
36fc0 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69 2d   within a multi-
36fd0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72 61  statement.** tra
36fe0 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72 73  nsaction (errors
36ff0 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c 49   including [SQLI
37000 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49 54  TE_FULL], [SQLIT
37010 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53 51  E_IOERR],.** [SQ
37020 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53 51  LITE_NOMEM], [SQ
37030 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64 20  LITE_BUSY], and 
37040 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
37050 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  T]) then the.** 
37060 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67 68  transaction migh
37070 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b  t be rolled back
37080 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
37090 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20 74 6f   The only way to
370a0 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77 68 65  .** find out whe
370b0 74 68 65 72 20 53 51 4c 69 74 65 20 61 75 74 6f  ther SQLite auto
370c0 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
370d0 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61   back the transa
370e0 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a 20 61  ction after.** a
370f0 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20 75 73  n error is to us
37100 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  e this function.
37110 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74 68 65  .**.** If anothe
37120 72 20 74 68 72 65 61 64 20 63 68 61 6e 67 65 73  r thread changes
37130 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69 74 20   the autocommit 
37140 73 74 61 74 75 73 20 6f 66 20 74 68 65 20 64 61  status of the da
37150 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
37160 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69 73 20  tion while this 
37170 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e 6e 69  routine is runni
37180 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 74  ng, then the ret
37190 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  urn value.** is 
371a0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51  undefined..*/.SQ
371b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
371c0 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d  ite3_get_autocom
371d0 6d 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  mit(sqlite3*);..
371e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
371f0 46 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73  Find The Databas
37200 65 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72  e Handle Of A Pr
37210 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
37220 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37230 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e  te3_db_handle in
37240 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
37250 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
37260 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
37270 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b  .** to which a [
37280 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37290 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54  nt] belongs.  ^T
372a0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
372b0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75  nection].** retu
372c0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
372d0 64 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65  db_handle is the
372e0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
372f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74  connection].** t
37300 68 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73  hat was the firs
37310 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
37320 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72   the [sqlite3_pr
37330 65 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c  epare_v2()] call
37340 20 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74   (or its variant
37350 73 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64  s) that was used
37360 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68   to.** create th
37370 65 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  e statement in t
37380 68 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a  he first place..
37390 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
373a0 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 64  lite3 *sqlite3_d
373b0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
373c0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
373d0 43 41 50 49 33 52 45 46 3a 20 52 65 74 75 72 6e  CAPI3REF: Return
373e0 20 54 68 65 20 46 69 6c 65 6e 61 6d 65 20 46 6f   The Filename Fo
373f0 72 20 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e  r A Database Con
37400 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54  nection.**.** ^T
37410 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 66 69  he sqlite3_db_fi
37420 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69 6e 74 65  lename(D,N) inte
37430 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
37440 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 69 6c  pointer to a fil
37450 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f 63 69 61  ename.** associa
37460 74 65 64 20 77 69 74 68 20 64 61 74 61 62 61 73  ted with databas
37470 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f  e N of connectio
37480 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61 69 6e 20  n D.  ^The main 
37490 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
374a0 20 68 61 73 20 74 68 65 20 6e 61 6d 65 20 22 6d   has the name "m
374b0 61 69 6e 22 2e 20 20 49 66 20 74 68 65 72 65 20  ain".  If there 
374c0 69 73 20 6e 6f 20 61 74 74 61 63 68 65 64 20 64  is no attached d
374d0 61 74 61 62 61 73 65 20 4e 20 6f 6e 20 74 68 65  atabase N on the
374e0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
374f0 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72 20 69 66  nection D, or if
37500 20 64 61 74 61 62 61 73 65 20 4e 20 69 73 20 61   database N is a
37510 20 74 65 6d 70 6f 72 61 72 79 20 6f 72 20 69 6e   temporary or in
37520 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
37530 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c  , then.** a NULL
37540 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
37550 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
37560 20 66 69 6c 65 6e 61 6d 65 20 72 65 74 75 72 6e   filename return
37570 65 64 20 62 79 20 74 68 69 73 20 66 75 6e 63 74  ed by this funct
37580 69 6f 6e 20 69 73 20 74 68 65 20 6f 75 74 70 75  ion is the outpu
37590 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 46 75 6c  t of the.** xFul
375a0 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74 68 6f 64  lPathname method
375b0 20 6f 66 20 74 68 65 20 5b 56 46 53 5d 2e 20 20   of the [VFS].  
375c0 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  ^In other words,
375d0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
375e0 20 77 69 6c 6c 20 62 65 20 61 6e 20 61 62 73 6f   will be an abso
375f0 6c 75 74 65 20 70 61 74 68 6e 61 6d 65 2c 20 65  lute pathname, e
37600 76 65 6e 20 69 66 20 74 68 65 20 66 69 6c 65 6e  ven if the filen
37610 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74 6f 20 6f  ame used.** to o
37620 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
37630 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77 61 73 20   originally was 
37640 61 20 55 52 49 20 6f 72 20 72 65 6c 61 74 69 76  a URI or relativ
37650 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 53  e pathname..*/.S
37660 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
37670 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 62  char *sqlite3_db
37680 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74 65  _filename(sqlite
37690 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61  3 *db, const cha
376a0 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a  r *zDbName);../*
376b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
376c0 74 65 72 6d 69 6e 65 20 69 66 20 61 20 64 61 74  termine if a dat
376d0 61 62 61 73 65 20 69 73 20 72 65 61 64 2d 6f 6e  abase is read-on
376e0 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ly.**.** ^The sq
376f0 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e 6c  lite3_db_readonl
37700 79 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  y(D,N) interface
37710 20 72 65 74 75 72 6e 73 20 31 20 69 66 20 74 68   returns 1 if th
37720 65 20 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a 20  e database N.** 
37730 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 20  of connection D 
37740 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30 20  is read-only, 0 
37750 69 66 20 69 74 20 69 73 20 72 65 61 64 2f 77 72  if it is read/wr
37760 69 74 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e 20  ite, or -1 if N 
37770 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e 61  is not.** the na
37780 6d 65 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  me of a database
37790 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44   on connection D
377a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
377b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 72  int sqlite3_db_r
377c0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 20  eadonly(sqlite3 
377d0 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  *db, const char 
377e0 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  *zDbName);../*.*
377f0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e 64  * CAPI3REF: Find
37800 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61 72   the next prepar
37810 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed statement.**.
37820 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
37830 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
37840 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78 74  nter to the next
37850 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
37860 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20 70  ment] after.** p
37870 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64 20  Stmt associated 
37880 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
37890 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
378a0 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20 69  Db.  ^If pStmt i
378b0 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20 74  s NULL.** then t
378c0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72 65  his interface re
378d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
378e0 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72 65  to the first pre
378f0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
37900 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
37910 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65 20  th the database 
37920 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e 20  connection pDb. 
37930 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65 64   ^If no prepared
37940 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73 61   statement.** sa
37950 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e 64  tisfies the cond
37960 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20 72  itions of this r
37970 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75 72  outine, it retur
37980 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  ns NULL..**.** T
37990 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
379a0 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65 72  nection] pointer
379b0 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f 0a   D in a call to.
379c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74  ** [sqlite3_next
379d0 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73 74  _stmt(D,S)] must
379e0 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70 65   refer to an ope
379f0 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  n database.** co
37a00 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e 20  nnection and in 
37a10 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74 20  particular must 
37a20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  not be a NULL po
37a30 69 6e 74 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  inter..*/.SQLITE
37a40 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 73 74 6d  _API sqlite3_stm
37a50 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f  t *sqlite3_next_
37a60 73 74 6d 74 28 73 71 6c 69 74 65 33 20 2a 70 44  stmt(sqlite3 *pD
37a70 62 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  b, sqlite3_stmt 
37a80 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
37a90 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 6d 69 74  CAPI3REF: Commit
37aa0 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b 20 4e 6f   And Rollback No
37ab0 74 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62  tification Callb
37ac0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  acks.**.** ^The 
37ad0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
37ae0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
37af0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
37b00 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
37b10 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
37b20 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
37b30 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d 4d 49 54  ction is [COMMIT
37b40 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d 2e 0a 2a   | committed]..*
37b50 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
37b60 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
37b70 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  s call to sqlite
37b80 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 0a  3_commit_hook().
37b90 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
37ba0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37bb0 69 6f 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65  ion is overridde
37bc0 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  n..** ^The sqlit
37bd0 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
37be0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
37bf0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
37c00 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f  k.** function to
37c10 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
37c20 65 76 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  ever a transacti
37c30 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41 43 4b 20  on is [ROLLBACK 
37c40 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b 5d 2e 0a  | rolled back]..
37c50 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b  ** ^Any callback
37c60 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f   set by a previo
37c70 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  us call to sqlit
37c80 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b  e3_rollback_hook
37c90 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
37ca0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
37cb0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
37cc0 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 70 41  dden..** ^The pA
37cd0 72 67 20 61 72 67 75 6d 65 6e 74 20 69 73 20 70  rg argument is p
37ce0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 74 6f  assed through to
37cf0 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a   the callback..*
37d00 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
37d10 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69 74 20 68  ck on a commit h
37d20 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  ook function ret
37d30 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a  urns non-zero,.*
37d40 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69  * then the commi
37d50 74 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  t is converted i
37d60 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63 6b 2e 0a  nto a rollback..
37d70 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37d80 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 44  e3_commit_hook(D
37d90 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c 69 74 65  ,C,P) and sqlite
37da0 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28  3_rollback_hook(
37db0 44 2c 43 2c 50 29 20 66 75 6e 63 74 69 6f 6e 73  D,C,P) functions
37dc0 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68 65 20 50  .** return the P
37dd0 20 61 72 67 75 6d 65 6e 74 20 66 72 6f 6d 20 74   argument from t
37de0 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
37df0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
37e00 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74 68 65 20  ction.** on the 
37e10 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
37e20 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c 20 6f 72  onnection] D, or
37e30 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20 74 68 65   NULL for.** the
37e40 20 66 69 72 73 74 20 63 61 6c 6c 20 66 6f 72 20   first call for 
37e50 65 61 63 68 20 66 75 6e 63 74 69 6f 6e 20 6f 6e  each function on
37e60 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f   D..**.** The co
37e70 6d 6d 69 74 20 61 6e 64 20 72 6f 6c 6c 62 61 63  mmit and rollbac
37e80 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 73  k hook callbacks
37e90 20 61 72 65 20 6e 6f 74 20 72 65 65 6e 74 72 61   are not reentra
37ea0 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  nt..** The callb
37eb0 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ack implementati
37ec0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  on must not do a
37ed0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
37ee0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
37ef0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37f00 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
37f10 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 20 20   the callback.  
37f20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74  Any actions.** t
37f30 6f 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74  o modify the dat
37f40 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37f50 20 6d 75 73 74 20 62 65 20 64 65 66 65 72 72 65   must be deferre
37f60 64 20 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68  d until after th
37f70 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20  e.** completion 
37f80 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
37f90 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61  step()] call tha
37fa0 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65 20  t triggered the 
37fb0 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20 72 6f 6c  commit.** or rol
37fc0 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e 20 74 68  lback hook in th
37fd0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
37fe0 2a 20 4e 6f 74 65 20 74 68 61 74 20 72 75 6e 6e  * Note that runn
37ff0 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
38000 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c 20 69 6e  L statements, in
38010 63 6c 75 64 69 6e 67 20 53 45 4c 45 43 54 20 73  cluding SELECT s
38020 74 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a 20 6f 72  tatements,.** or
38030 20 6d 65 72 65 6c 79 20 63 61 6c 6c 69 6e 67 20   merely calling 
38040 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
38050 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
38060 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
38070 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
38080 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
38090 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
380a0 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
380b0 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
380c0 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 69 73 74  h..**.** ^Regist
380d0 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20 66 75 6e  ering a NULL fun
380e0 63 74 69 6f 6e 20 64 69 73 61 62 6c 65 73 20 74  ction disables t
380f0 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  he callback..**.
38100 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 63 6f 6d  ** ^When the com
38110 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c 62 61 63  mit hook callbac
38120 6b 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  k routine return
38130 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b 43 4f 4d  s zero, the [COM
38140 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  MIT].** operatio
38150 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20 74 6f 20  n is allowed to 
38160 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d 61 6c 6c  continue normall
38170 79 2e 20 20 5e 49 66 20 74 68 65 20 63 6f 6d 6d  y.  ^If the comm
38180 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65 74 75 72  it hook.** retur
38190 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
381a0 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 20 69  n the [COMMIT] i
381b0 73 20 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f  s converted into
381c0 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a   a [ROLLBACK]..*
381d0 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20  * ^The rollback 
381e0 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  hook is invoked 
381f0 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b 20 74 68  on a rollback th
38200 61 74 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  at results from 
38210 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68 6f 6f 6b  a commit.** hook
38220 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f 6e 2d 7a   returning non-z
38230 65 72 6f 2c 20 6a 75 73 74 20 61 73 20 69 74 20  ero, just as it 
38240 77 6f 75 6c 64 20 62 65 20 77 69 74 68 20 61 6e  would be with an
38250 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62 61 63 6b  y other rollback
38260 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ..**.** ^For the
38270 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
38280 73 20 41 50 49 2c 20 61 20 74 72 61 6e 73 61 63  s API, a transac
38290 74 69 6f 6e 20 69 73 20 73 61 69 64 20 74 6f 20  tion is said to 
382a0 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20 72 6f 6c  have been.** rol
382b0 6c 65 64 20 62 61 63 6b 20 69 66 20 61 6e 20 65  led back if an e
382c0 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c 42 41 43  xplicit "ROLLBAC
382d0 4b 22 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  K" statement is 
382e0 65 78 65 63 75 74 65 64 2c 20 6f 72 0a 2a 2a 20  executed, or.** 
382f0 61 6e 20 65 72 72 6f 72 20 6f 72 20 63 6f 6e 73  an error or cons
38300 74 72 61 69 6e 74 20 63 61 75 73 65 73 20 61 6e  traint causes an
38310 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c 6c 62 61   implicit rollba
38320 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a 2a 2a 20  ck to occur..** 
38330 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b 20 63 61  ^The rollback ca
38340 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74 20 69 6e  llback is not in
38350 76 6f 6b 65 64 20 69 66 20 61 20 74 72 61 6e 73  voked if a trans
38360 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 61 75 74  action is.** aut
38370 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
38380 64 20 62 61 63 6b 20 62 65 63 61 75 73 65 20 74  d back because t
38390 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
383a0 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64  ection is closed
383b0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
383c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 75 70   the [sqlite3_up
383d0 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20 69 6e 74  date_hook()] int
383e0 65 72 66 61 63 65 2e 0a 2a 2f 0a 53 51 4c 49 54  erface..*/.SQLIT
383f0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
38400 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
38410 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
38420 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
38430 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
38440 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61   *sqlite3_rollba
38450 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33 2a  ck_hook(sqlite3*
38460 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20 2a  , void(*)(void *
38470 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
38480 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61  * CAPI3REF: Data
38490 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63 61   Change Notifica
384a0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
384b0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
384c0 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 20  3_update_hook() 
384d0 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
384e0 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
384f0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
38500 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
38510 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74 69  nnection] identi
38520 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
38530 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  t argument.** to
38540 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
38550 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75 70  ever a row is up
38560 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
38570 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  or deleted..** ^
38580 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74  Any callback set
38590 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63   by a previous c
385a0 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e 63  all to this func
385b0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65 20  tion.** for the 
385c0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
385d0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72  nnection is over
385e0 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ridden..**.** ^T
385f0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
38600 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  nt is a pointer 
38610 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  to the function 
38620 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20 61  to invoke when a
38630 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61 74  .** row is updat
38640 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72 20  ed, inserted or 
38650 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68 65  deleted..** ^The
38660 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
38670 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
38680 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
38690 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a   third argument.
386a0 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75 70  ** to sqlite3_up
386b0 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a 20  date_hook()..** 
386c0 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c 6c  ^The second call
386d0 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73  back argument is
386e0 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
386f0 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54 45  INSERT], [SQLITE
38700 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72 20  _DELETE],.** or 
38710 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d 2c  [SQLITE_UPDATE],
38720 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
38730 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  e operation that
38740 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c 6c   caused the call
38750 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69 6e  back.** to be in
38760 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 74  voked..** ^The t
38770 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20  hird and fourth 
38780 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 65  arguments to the
38790 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69   callback contai
387a0 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  n pointers to th
387b0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61 6e  e.** datab