System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 0060c2d9fa6e69c5107232f694894fd0fd14347d:


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 2e 31 22 0a 23 64 65 66 69 6e 65  .7.15.1".#define
1030: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1040: 4e 55 4d 42 45 52 20 33 30 30 37 30 31 35 0a 23  NUMBER 3007015.#
1050: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f  define SQLITE_SO
1060: 55 52 43 45 5f 49 44 20 20 20 20 20 20 22 32 30  URCE_ID      "20
1070: 31 32 2d 31 32 2d 31 39 20 32 30 3a 33 39 3a 31  12-12-19 20:39:1
1080: 30 20 36 62 38 35 62 37 36 37 64 30 66 66 37 39  0 6b85b767d0ff79
1090: 37 35 31 34 36 31 35 36 61 39 39 61 64 36 37 33  75146156a99ad673
10a0: 66 32 63 31 61 32 33 33 31 38 22 0a 0a 2f 2a 0a  f2c1a23318"../*.
10b0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
10c0: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
10d0: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a  rsion Numbers.**
10e0: 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69 74   KEYWORDS: sqlit
10f0: 65 33 5f 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69  e3_version, sqli
1100: 74 65 33 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a  te3_sourceid.**.
1110: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 72 66 61  ** These interfa
1120: 63 65 73 20 70 72 6f 76 69 64 65 20 74 68 65 20  ces provide the 
1130: 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  same information
1140: 20 61 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   as the [SQLITE_
1150: 56 45 52 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51  VERSION],.** [SQ
1160: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1170: 42 45 52 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  BER], and [SQLIT
1180: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
1190: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
11a0: 6f 73 0a 2a 2a 20 62 75 74 20 61 72 65 20 61 73  os.** but are as
11b0: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
11c0: 65 20 6c 69 62 72 61 72 79 20 69 6e 73 74 65 61  e library instea
11d0: 64 20 6f 66 20 74 68 65 20 68 65 61 64 65 72 20  d of the header 
11e0: 66 69 6c 65 2e 20 20 5e 28 43 61 75 74 69 6f 75  file.  ^(Cautiou
11f0: 73 0a 2a 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73  s.** programmers
1200: 20 6d 69 67 68 74 20 69 6e 63 6c 75 64 65 20 61   might include a
1210: 73 73 65 72 74 28 29 20 73 74 61 74 65 6d 65 6e  ssert() statemen
1220: 74 73 20 69 6e 20 74 68 65 69 72 20 61 70 70 6c  ts in their appl
1230: 69 63 61 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65  ication to.** ve
1240: 72 69 66 79 20 74 68 61 74 20 76 61 6c 75 65 73  rify that values
1250: 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
1260: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61  se interfaces ma
1270: 74 63 68 20 74 68 65 20 6d 61 63 72 6f 73 20 69  tch the macros i
1280: 6e 0a 2a 2a 20 74 68 65 20 68 65 61 64 65 72 2c  n.** the header,
1290: 20 61 6e 64 20 74 68 75 73 20 69 6e 73 75 72 65   and thus insure
12a0: 20 74 68 61 74 20 74 68 65 20 61 70 70 6c 69 63   that the applic
12b0: 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70  ation is.** comp
12c0: 69 6c 65 64 20 77 69 74 68 20 6d 61 74 63 68 69  iled with matchi
12d0: 6e 67 20 6c 69 62 72 61 72 79 20 61 6e 64 20 68  ng library and h
12e0: 65 61 64 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a  eader files..**.
12f0: 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1300: 70 72 65 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20  pre>.** assert( 
1310: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1320: 6f 6e 5f 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c  on_number()==SQL
1330: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
1340: 45 52 20 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28  ER );.** assert(
1350: 20 73 74 72 63 6d 70 28 73 71 6c 69 74 65 33 5f   strcmp(sqlite3_
1360: 73 6f 75 72 63 65 69 64 28 29 2c 53 51 4c 49 54  sourceid(),SQLIT
1370: 45 5f 53 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20  E_SOURCE_ID)==0 
1380: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1390: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 6c 69 62  rcmp(sqlite3_lib
13a0: 76 65 72 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45  version(),SQLITE
13b0: 5f 56 45 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a  _VERSION)==0 );.
13c0: 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
13d0: 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
13e0: 54 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  The sqlite3_vers
13f0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
1400: 73 74 61 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74  stant contains t
1410: 68 65 20 74 65 78 74 20 6f 66 20 5b 53 51 4c 49  he text of [SQLI
1420: 54 45 5f 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d  TE_VERSION].** m
1430: 61 63 72 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69  acro.  ^The sqli
1440: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
1450: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1460: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
1470: 68 65 0a 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c  he.** to the sql
1480: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
1490: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20  tring constant. 
14a0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62   The sqlite3_lib
14b0: 76 65 72 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e  version().** fun
14c0: 63 74 69 6f 6e 20 69 73 20 70 72 6f 76 69 64 65  ction is provide
14d0: 64 20 66 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c  d for use in DLL
14e0: 73 20 73 69 6e 63 65 20 44 4c 4c 20 75 73 65 72  s since DLL user
14f0: 73 20 75 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74  s usually do not
1500: 20 68 61 76 65 0a 2a 2a 20 64 69 72 65 63 74 20   have.** direct 
1510: 61 63 63 65 73 73 20 74 6f 20 73 74 72 69 6e 67  access to string
1520: 20 63 6f 6e 73 74 61 6e 74 73 20 77 69 74 68 69   constants withi
1530: 6e 20 74 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65  n the DLL.  ^The
1540: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6c 69 62 76  .** sqlite3_libv
1550: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20  ersion_number() 
1560: 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1570: 20 61 6e 20 69 6e 74 65 67 65 72 20 65 71 75 61   an integer equa
1580: 6c 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  l to.** [SQLITE_
1590: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e  VERSION_NUMBER].
15a0: 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73    ^The sqlite3_s
15b0: 6f 75 72 63 65 69 64 28 29 20 66 75 6e 63 74 69  ourceid() functi
15c0: 6f 6e 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61  on returns .** a
15d0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 73 74   pointer to a st
15e0: 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 77 68  ring constant wh
15f0: 6f 73 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  ose value is the
1600: 20 73 61 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a   same as the .**
1610: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
1620: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
1630: 6f 72 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  or macro..**.** 
1640: 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
1650: 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64  e_version()] and
1660: 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f   [sqlite_source_
1670: 69 64 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  id()]..*/.SQLITE
1680: 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45  _API SQLITE_EXTE
1690: 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73 71  RN const char sq
16a0: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b  lite3_version[];
16b0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
16c0: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
16d0: 6c 69 62 76 65 72 73 69 6f 6e 28 76 6f 69 64 29  libversion(void)
16e0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
16f0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1700: 5f 73 6f 75 72 63 65 69 64 28 76 6f 69 64 29 3b  _sourceid(void);
1710: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1720: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1730: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
1740: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1750: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
1760: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
1770: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1780: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1790: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
17a0: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
17b0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
17c0: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
17d0: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
17e0: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
17f0: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1800: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1810: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
1820: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
1830: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
1840: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
1850: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
1860: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
1870: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1880: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1890: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
18a0: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
18b0: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
18c0: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
18d0: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
18e0: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
18f0: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1900: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1910: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
1920: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
1930: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
1940: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
1950: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1960: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
1970: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1980: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1990: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
19a0: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
19b0: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
19c0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
19d0: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
19e0: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
19f0: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1a00: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1a10: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1a20: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
1a30: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1a40: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
1a50: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
1a60: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
1a70: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a80: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a90: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1aa0: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1ab0: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1ac0: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1ad0: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1ae0: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1af0: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1b00: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1b10: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1b20: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1b30: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1b40: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1b50: 41 47 53 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  AGS.SQLITE_API i
1b60: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  nt sqlite3_compi
1b70: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f  leoption_used(co
1b80: 6e 73 74 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61  nst char *zOptNa
1b90: 6d 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  me);.SQLITE_API 
1ba0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
1bb0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
1bc0: 6e 5f 67 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65  n_get(int N);.#e
1bd0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
1be0: 33 52 45 46 3a 20 54 65 73 74 20 54 6f 20 53 65  3REF: Test To Se
1bf0: 65 20 49 66 20 54 68 65 20 4c 69 62 72 61 72 79  e If The Library
1c00: 20 49 73 20 54 68 72 65 61 64 73 61 66 65 0a 2a   Is Threadsafe.*
1c10: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1c20: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 20 66  3_threadsafe() f
1c30: 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1c40: 7a 65 72 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79  zero if and only
1c50: 20 69 66 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61   if.** SQLite wa
1c60: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
1c70: 6d 75 74 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d  mutexing code om
1c80: 69 74 74 65 64 20 64 75 65 20 74 6f 20 74 68 65  itted due to the
1c90: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  .** [SQLITE_THRE
1ca0: 41 44 53 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d  ADSAFE] compile-
1cb0: 74 69 6d 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e  time option bein
1cc0: 67 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a  g set to 0..**.*
1cd0: 2a 20 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  * SQLite can be 
1ce0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6f 72  compiled with or
1cf0: 20 77 69 74 68 6f 75 74 20 6d 75 74 65 78 65 73   without mutexes
1d00: 2e 20 20 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b  .  When.** the [
1d10: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1d20: 45 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f  E] C preprocesso
1d30: 72 20 6d 61 63 72 6f 20 69 73 20 31 20 6f 72 20  r macro is 1 or 
1d40: 32 2c 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  2, mutexes.** ar
1d50: 65 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 53 51  e enabled and SQ
1d60: 4c 69 74 65 20 69 73 20 74 68 72 65 61 64 73 61  Lite is threadsa
1d70: 66 65 2e 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a  fe.  When the.**
1d80: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1d90: 41 46 45 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c  AFE] macro is 0,
1da0: 20 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65 73   .** the mutexes
1db0: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 20 20 57   are omitted.  W
1dc0: 69 74 68 6f 75 74 20 74 68 65 20 6d 75 74 65 78  ithout the mutex
1dd0: 65 73 2c 20 69 74 20 69 73 20 6e 6f 74 20 73 61  es, it is not sa
1de0: 66 65 0a 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c  fe.** to use SQL
1df0: 69 74 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79  ite concurrently
1e00: 20 66 72 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20   from more than 
1e10: 6f 6e 65 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a  one thread..**.*
1e20: 2a 20 45 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78  * Enabling mutex
1e30: 65 73 20 69 6e 63 75 72 73 20 61 20 6d 65 61 73  es incurs a meas
1e40: 75 72 61 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e  urable performan
1e50: 63 65 20 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53  ce penalty..** S
1e60: 6f 20 69 66 20 73 70 65 65 64 20 69 73 20 6f 66  o if speed is of
1e70: 20 75 74 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e   utmost importan
1e80: 63 65 2c 20 69 74 20 6d 61 6b 65 73 20 73 65 6e  ce, it makes sen
1e90: 73 65 20 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a  se to disable.**
1ea0: 20 74 68 65 20 6d 75 74 65 78 65 73 2e 20 20 42   the mutexes.  B
1eb0: 75 74 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73  ut for maximum s
1ec0: 61 66 65 74 79 2c 20 6d 75 74 65 78 65 73 20 73  afety, mutexes s
1ed0: 68 6f 75 6c 64 20 62 65 20 65 6e 61 62 6c 65 64  hould be enabled
1ee0: 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  ..** ^The defaul
1ef0: 74 20 62 65 68 61 76 69 6f 72 20 69 73 20 66 6f  t behavior is fo
1f00: 72 20 6d 75 74 65 78 65 73 20 74 6f 20 62 65 20  r mutexes to be 
1f10: 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  enabled..**.** T
1f20: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
1f30: 6e 20 62 65 20 75 73 65 64 20 62 79 20 61 6e 20  n be used by an 
1f40: 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d  application to m
1f50: 61 6b 65 20 73 75 72 65 20 74 68 61 74 20 74 68  ake sure that th
1f60: 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20  e.** version of 
1f70: 53 51 4c 69 74 65 20 74 68 61 74 20 69 74 20 69  SQLite that it i
1f80: 73 20 6c 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73  s linking agains
1f90: 74 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  t was compiled w
1fa0: 69 74 68 0a 2a 2a 20 74 68 65 20 64 65 73 69 72  ith.** the desir
1fb0: 65 64 20 73 65 74 74 69 6e 67 20 6f 66 20 74 68  ed setting of th
1fc0: 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
1fd0: 53 41 46 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a  SAFE] macro..**.
1fe0: 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
1ff0: 65 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f  e only reports o
2000: 6e 20 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69  n the compile-ti
2010: 6d 65 20 6d 75 74 65 78 20 73 65 74 74 69 6e 67  me mutex setting
2020: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
2030: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 66  TE_THREADSAFE] f
2040: 6c 61 67 2e 20 20 49 66 20 53 51 4c 69 74 65 20  lag.  If SQLite 
2050: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
2060: 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 48 52 45 41  .** SQLITE_THREA
2070: 44 53 41 46 45 3d 31 20 6f 72 20 3d 32 20 74 68  DSAFE=1 or =2 th
2080: 65 6e 20 6d 75 74 65 78 65 73 20 61 72 65 20 65  en mutexes are e
2090: 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
20a0: 74 20 62 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20  t but.** can be 
20b0: 66 75 6c 6c 79 20 6f 72 20 70 61 72 74 69 61 6c  fully or partial
20c0: 6c 79 20 64 69 73 61 62 6c 65 64 20 75 73 69 6e  ly disabled usin
20d0: 67 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  g a call to [sql
20e0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a  ite3_config()].*
20f0: 2a 20 77 69 74 68 20 74 68 65 20 76 65 72 62 73  * with the verbs
2100: 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2110: 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b  SINGLETHREAD], [
2120: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2130: 4c 54 49 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f  LTITHREAD],.** o
2140: 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
2150: 5f 4d 55 54 45 58 5d 2e 20 20 5e 28 54 68 65 20  _MUTEX].  ^(The 
2160: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
2170: 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74  the.** sqlite3_t
2180: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
2190: 74 69 6f 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20  tion shows only 
21a0: 74 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  the compile-time
21b0: 20 73 65 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74   setting of.** t
21c0: 68 72 65 61 64 20 73 61 66 65 74 79 2c 20 6e 6f  hread safety, no
21d0: 74 20 61 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63  t any run-time c
21e0: 68 61 6e 67 65 73 20 74 6f 20 74 68 61 74 20 73  hanges to that s
21f0: 65 74 74 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a  etting made by.*
2200: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  * sqlite3_config
2210: 28 29 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  (). In other wor
2220: 64 73 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ds, the return v
2230: 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
2240: 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 0a 2a  3_threadsafe().*
2250: 2a 20 69 73 20 75 6e 63 68 61 6e 67 65 64 20 62  * is unchanged b
2260: 79 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  y calls to sqlit
2270: 65 33 5f 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a  e3_config().)^.*
2280: 2a 0a 2a 2a 20 53 65 65 20 74 68 65 20 5b 74 68  *.** See the [th
2290: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f  reading mode] do
22a0: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
22b0: 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
22c0: 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  mation..*/.SQLIT
22d0: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
22e0: 33 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69  3_threadsafe(voi
22f0: 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  d);../*.** CAPI3
2300: 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f  REF: Database Co
2310: 6e 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a  nnection Handle.
2320: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61  ** KEYWORDS: {da
2330: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2340: 6e 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e  n} {database con
2350: 6e 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  nections}.**.** 
2360: 45 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65  Each open SQLite
2370: 20 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70   database is rep
2380: 72 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f  resented by a po
2390: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
23a0: 61 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f  ance of.** the o
23b0: 70 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20  paque structure 
23c0: 6e 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e  named "sqlite3".
23d0: 20 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74    It is useful t
23e0: 6f 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71  o think of an sq
23f0: 6c 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72  lite3.** pointer
2400: 20 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20   as an object.  
2410: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  The [sqlite3_ope
2420: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2430: 70 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a  pen16()], and.**
2440: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
2450: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  2()] interfaces 
2460: 61 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63  are its construc
2470: 74 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74  tors, and [sqlit
2480: 65 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61  e3_close()].** a
2490: 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  nd [sqlite3_clos
24a0: 65 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20  e_v2()] are its 
24b0: 64 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68  destructors.  Th
24c0: 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68  ere are many oth
24d0: 65 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  er.** interfaces
24e0: 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71   (such as.** [sq
24f0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2500: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
2510: 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
2520: 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2530: 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29  3_busy_timeout()
2540: 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68  ] to name but th
2550: 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65  ree) that are me
2560: 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73  thods on an.** s
2570: 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a  qlite3 object..*
2580: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
2590: 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33   sqlite3 sqlite3
25a0: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
25b0: 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65  F: 64-Bit Intege
25c0: 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f  r Types.** KEYWO
25d0: 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36  RDS: sqlite_int6
25e0: 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a  4 sqlite_uint64.
25f0: 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
2600: 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d  ere is no cross-
2610: 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20  platform way to 
2620: 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69  specify 64-bit i
2630: 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20  nteger types.** 
2640: 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20  SQLite includes 
2650: 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d  typedefs for 64-
2660: 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75  bit signed and u
2670: 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73  nsigned integers
2680: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
2690: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
26a0: 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65  lite3_uint64 are
26b0: 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
26c0: 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e  ype definitions.
26d0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69  .** The sqlite_i
26e0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
26f0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65  uint64 types are
2700: 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62   supported for b
2710: 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70  ackwards.** comp
2720: 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a  atibility only..
2730: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2740: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2750: 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20  ite_int64 types 
2760: 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65  can store intege
2770: 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77  r values.** betw
2780: 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38  een -92233720368
2790: 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32  54775808 and +92
27a0: 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30  2337203685477580
27b0: 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54  7 inclusive.  ^T
27c0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69  he.** sqlite3_ui
27d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
27e0: 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  uint64 types can
27f0: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
2800: 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65  alues .** betwee
2810: 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34  n 0 and +1844674
2820: 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e  4073709551615 in
2830: 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64  clusive..*/.#ifd
2840: 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ef SQLITE_INT64_
2850: 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53  TYPE.  typedef S
2860: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2870: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20   sqlite_int64;. 
2880: 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65   typedef unsigne
2890: 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  d SQLITE_INT64_T
28a0: 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36  YPE sqlite_uint6
28b0: 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64  4;.#elif defined
28c0: 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65  (_MSC_VER) || de
28d0: 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43  fined(__BORLANDC
28e0: 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f  __).  typedef __
28f0: 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74  int64 sqlite_int
2900: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
2910: 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73  signed __int64 s
2920: 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65  qlite_uint64;.#e
2930: 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f  lse.  typedef lo
2940: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
2950: 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65  te_int64;.  type
2960: 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e  def unsigned lon
2970: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
2980: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66  e_uint64;.#endif
2990: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
29a0: 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e  int64 sqlite3_in
29b0: 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c  t64;.typedef sql
29c0: 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74  ite_uint64 sqlit
29d0: 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a  e3_uint64;../*.*
29e0: 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66  * If compiling f
29f0: 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74  or a processor t
2a00: 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69  hat lacks floati
2a10: 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74  ng point support
2a20: 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20  ,.** substitute 
2a30: 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61  integer for floa
2a40: 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23  ting-point..*/.#
2a50: 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  ifdef SQLITE_OMI
2a60: 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54  T_FLOATING_POINT
2a70: 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65  .# define double
2a80: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23   sqlite3_int64.#
2a90: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
2aa0: 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41  I3REF: Closing A
2ab0: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2ac0: 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tion.**.** ^The 
2ad0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2ae0: 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  and sqlite3_clos
2af0: 65 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20  e_v2() routines 
2b00: 61 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a  are destructors.
2b10: 2a 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  ** for the [sqli
2b20: 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  te3] object..** 
2b30: 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65  ^Calls to sqlite
2b40: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71  3_close() and sq
2b50: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2b60: 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f   return SQLITE_O
2b70: 4b 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  K if.** the [sql
2b80: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
2b90: 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73  successfully des
2ba0: 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61  troyed and all a
2bb0: 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73  ssociated.** res
2bc0: 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c  ources are deall
2bd0: 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ocated..**.** ^I
2be0: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
2bf0: 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73  onnection is ass
2c00: 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66  ociated with unf
2c10: 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65  inalized prepare
2c20: 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20  d.** statements 
2c30: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2c40: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a  lite3_backup obj
2c50: 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65  ects then sqlite
2c60: 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c  3_close().** wil
2c70: 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61  l leave the data
2c80: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2c90: 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20  open and return 
2ca0: 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a  [SQLITE_BUSY]..*
2cb0: 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c  * ^If sqlite3_cl
2cc0: 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c  ose_v2() is call
2cd0: 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69  ed with unfinali
2ce0: 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61  zed prepared sta
2cf0: 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75  tements.** and u
2d00: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
2d10: 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20  3_backups, then 
2d20: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2d30: 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a  nection becomes.
2d40: 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22  ** an unusable "
2d50: 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69  zombie" which wi
2d60: 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
2d70: 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
2d80: 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74  when the.** last
2d90: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2da0: 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64  ent is finalized
2db0: 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c   or the last sql
2dc0: 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a  ite3_backup is.*
2dd0: 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65  * finished.  The
2de0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2df0: 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  2() interface is
2e00: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
2e10: 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c  e with.** host l
2e20: 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72  anguages that ar
2e30: 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63  e garbage collec
2e40: 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74  ted, and where t
2e50: 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63  he order in whic
2e60: 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73  h.** destructors
2e70: 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61   are called is a
2e80: 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20  rbitrary..**.** 
2e90: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
2ea0: 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  uld [sqlite3_fin
2eb0: 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2ec0: 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20  ] all [prepared 
2ed0: 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20  statements],.** 
2ee0: 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c  [sqlite3_blob_cl
2ef0: 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c  ose | close] all
2f00: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
2f10: 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
2f20: 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20  3_backup_finish 
2f30: 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73  | finish] all [s
2f40: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
2f50: 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65  bjects associate
2f60: 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73  d.** with the [s
2f70: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70  qlite3] object p
2f80: 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69  rior to attempti
2f90: 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20  ng to close the 
2fa0: 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20  object.  ^If.** 
2fb0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
2fc0: 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b  is called on a [
2fd0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2fe0: 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20  ion] that still 
2ff0: 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69  has.** outstandi
3000: 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ng [prepared sta
3010: 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20  tements], [BLOB 
3020: 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72  handles], and/or
3030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63  .** [sqlite3_bac
3040: 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65  kup] objects the
3050: 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c  n it returns SQL
3060: 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64  ITE_OK but the d
3070: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
3080: 66 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64  f resources is d
3090: 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c  eferred until al
30a0: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
30b0: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
30c0: 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20  andles],.** and 
30d0: 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d  [sqlite3_backup]
30e0: 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73   objects are als
30f0: 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a  o destroyed..**.
3100: 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74  ** ^If an [sqlit
3110: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65  e3] object is de
3120: 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20  stroyed while a 
3130: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
3140: 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e  pen,.** the tran
3150: 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d  saction is autom
3160: 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20  atically rolled 
3170: 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  back..**.** The 
3180: 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  C parameter to [
3190: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29  sqlite3_close(C)
31a0: 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
31b0: 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d  lose_v2(C)].** m
31c0: 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20  ust be either a 
31d0: 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  NULL.** pointer 
31e0: 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20  or an [sqlite3] 
31f0: 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f  object pointer o
3200: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3210: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
3220: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
3230: 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
3240: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c  ite3_open_v2()],
3250: 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75   and not previou
3260: 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e  sly closed..** ^
3270: 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
3280: 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74  close() or sqlit
3290: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69  e3_close_v2() wi
32a0: 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
32b0: 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73  r.** argument is
32c0: 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
32d0: 70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  p..*/.SQLITE_API
32e0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f   int sqlite3_clo
32f0: 73 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  se(sqlite3*);.SQ
3300: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
3310: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71  ite3_close_v2(sq
3320: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
3330: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
3340: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
3350: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
3360: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
3370: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
3380: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
3390: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
33a0: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
33b0: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
33c0: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
33d0: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
33e0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
33f0: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
3400: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
3410: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
3420: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a  on Interface.**.
3430: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
3440: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3450: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  is a convenience
3460: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
3470: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
3480: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
3490: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
34a0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
34b0: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61  ze()],.** that a
34c0: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
34d0: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74  tion to run mult
34e0: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20  iple statements 
34f0: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75  of SQL.** withou
3500: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20  t having to use 
3510: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
3520: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
3530: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3540: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20  rface runs zero 
3550: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e  or more UTF-8 en
3560: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f  coded,.** semico
3570: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c  lon-separate SQL
3580: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
3590: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20  ed into its 2nd 
35a0: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20  argument,.** in 
35b0: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
35c0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
35d0: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20  nection] passed 
35e0: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a  in as its 1st.**
35f0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
3600: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
3610: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64  ction of the 3rd
3620: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
3630: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3640: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
3650: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66   it is invoked f
3660: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72  or each result r
3670: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74  ow.** coming out
3680: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65   of the evaluate
3690: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
36a0: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
36b0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
36c0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c  e3_exec() is rel
36d0: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ayed through to 
36e0: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74  the 1st argument
36f0: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c   of each.** call
3700: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  back invocation.
3710: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
3720: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  ck pointer to sq
3730: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3740: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f  is NULL, then no
3750: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65   callback is eve
3760: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65  r invoked and re
3770: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a  sult rows are.**
3780: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
3790: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  ^If an error occ
37a0: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61  urs while evalua
37b0: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61  ting the SQL sta
37c0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
37d0: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  nto.** sqlite3_e
37e0: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63  xec(), then exec
37f0: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
3800: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73  rent statement s
3810: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73  tops and.** subs
3820: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  equent statement
3830: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20  s are skipped.  
3840: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
3850: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3860: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f  _exec().** is no
3870: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20  t NULL then any 
3880: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73  error message is
3890: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
38a0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
38b0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
38c0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73  alloc()] and pas
38d0: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
38e0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
38f0: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  er..** To avoid 
3900: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68  memory leaks, th
3910: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
3920: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  ould invoke [sql
3930: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
3940: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  on error message
3950: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
3960: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  d through the 5t
3970: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a  h parameter of.*
3980: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  * of sqlite3_exe
3990: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72  c() after the er
39a0: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
39b0: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ng is no longer 
39c0: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  needed..** ^If t
39d0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
39e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
39f0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  () is not NULL a
3a00: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  nd no errors.** 
3a10: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69  occur, then sqli
3a20: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20  te3_exec() sets 
3a30: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69  the pointer in i
3a40: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  ts 5th parameter
3a50: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f   to.** NULL befo
3a60: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
3a70: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74  .** ^If an sqlit
3a80: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3a90: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
3aa0: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ero, the sqlite3
3ab0: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69  _exec().** routi
3ac0: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ne returns SQLIT
3ad0: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20  E_ABORT without 
3ae0: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c  invoking the cal
3af0: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a  lback again and.
3b00: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69  ** without runni
3b10: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ng any subsequen
3b20: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
3b30: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64  ..**.** ^The 2nd
3b40: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3b50: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3b60: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3b70: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  n is the.** numb
3b80: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
3b90: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54   the result.  ^T
3ba0: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3bb0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3bc0: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63  xec().** callbac
3bd0: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3be0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3bf0: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73  ings obtained as
3c00: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c   if from.** [sql
3c10: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
3c20: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63  ()], one for eac
3c30: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61  h column.  ^If a
3c40: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a  n element of a.*
3c50: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20  * result row is 
3c60: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
3c70: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69  rresponding stri
3c80: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  ng pointer for t
3c90: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
3ca0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
3cb0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
3cc0: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
3cd0: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71  ent to the.** sq
3ce0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3cf0: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
3d00: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3d10: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65   strings where e
3d20: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70  ach.** entry rep
3d30: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65  resents the name
3d40: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e   of correspondin
3d50: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  g result column 
3d60: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  as obtained.** f
3d70: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
3d80: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
3d90: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70  ** ^If the 2nd p
3da0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3db0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20  te3_exec() is a 
3dc0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20  NULL pointer, a 
3dd0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e  pointer.** to an
3de0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f   empty string, o
3df0: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  r a pointer that
3e00: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77   contains only w
3e10: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72  hitespace and/or
3e20: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74   .** SQL comment
3e30: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73  s, then no SQL s
3e40: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76  tatements are ev
3e50: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
3e60: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e  database.** is n
3e70: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
3e80: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  * Restrictions:.
3e90: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
3ea0: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3eb0: 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  on must insure t
3ec0: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61  hat the 1st para
3ed0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3ee0: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20  _exec().**      
3ef0: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f  is a valid and o
3f00: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
3f10: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c  nnection]..** <l
3f20: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3f30: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  on must not clos
3f40: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3f50: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3f60: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3f70: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3f80: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3f90: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3fa0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3fb0: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3fc0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3fd0: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3fe0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3ff0: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
4000: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
4010: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
4020: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
4030: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
4040: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
4050: 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
4060: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65   int sqlite3_exe
4070: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  c(.  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 20 20                  
40a0: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
40b0: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
40c0: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
40f0: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
4100: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28  int (*callback)(
4110: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
4120: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61  ,char**),  /* Ca
4130: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
4140: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 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 20 20                  
4170: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  /* 1st argument 
4180: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20  to callback */. 
4190: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **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 20 20 2f 2a 20 45              /* E
41c0: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
41d0: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   here */.);../*.
41e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
41f0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
4200: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b  WORDS: SQLITE_OK
4210: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65   {error code} {e
4220: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4230: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
4240: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63   code} {result c
4250: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  odes}.**.** Many
4260: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
4270: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
4280: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
4290: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
42a0: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72  wn.** here in or
42b0: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20  der to indicate 
42c0: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
42d0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72  re..**.** New er
42e0: 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65  ror codes may be
42f0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
4300: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4310: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ite..**.** See a
4320: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  lso: [SQLITE_IOE
4330: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
4340: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
4350: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74  ,.** [sqlite3_vt
4360: 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
4370: 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41  ] [SQLITE_ROLLBA
4380: 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  CK | result code
4390: 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s]..*/.#define S
43a0: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20  QLITE_OK        
43b0: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73     0   /* Succes
43c0: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f  sful result */./
43d0: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65  * beginning-of-e
43e0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64  rror-codes */.#d
43f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
4400: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a  OR        1   /*
4410: 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69   SQL error or mi
4420: 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a  ssing database *
4430: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4440: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20  _INTERNAL     2 
4450: 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f    /* Internal lo
4460: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c  gic error in SQL
4470: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ite */.#define S
4480: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20  QLITE_PERM      
4490: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73     3   /* Access
44a0: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69   permission deni
44b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
44c0: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20  LITE_ABORT      
44d0: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63    4   /* Callbac
44e0: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73  k routine reques
44f0: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a  ted an abort */.
4500: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
4510: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20  USY         5   
4520: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4530: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  file is locked *
4540: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4550: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20  _LOCKED       6 
4560: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20    /* A table in 
4570: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
4580: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4590: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20  e SQLITE_NOMEM  
45a0: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d        7   /* A m
45b0: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a  alloc() failed *
45c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
45d0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20  _READONLY     8 
45e0: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20    /* Attempt to 
45f0: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79  write a readonly
4600: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
4620: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20  RRUPT    9   /* 
4630: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e  Operation termin
4640: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
4650: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64  interrupt()*/.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4670: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a  RR       10   /*
4680: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69   Some kind of di
4690: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63  sk I/O error occ
46a0: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  urred */.#define
46b0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20   SQLITE_CORRUPT 
46c0: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20      11   /* The 
46d0: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d  database disk im
46e0: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64  age is malformed
46f0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4700: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31  TE_NOTFOUND    1
4710: 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f  2   /* Unknown o
4720: 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33  pcode in sqlite3
4730: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20  _file_control() 
4740: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4750: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
4760: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
4770: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
4780: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
4790: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
47a0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
47b0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
47c0: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
47d0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
47e0: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
47f0: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74  L    15   /* Dat
4800: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
4810: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
4820: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
4830: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
4840: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
4850: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4860: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
4870: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
4880: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
4890: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
48a0: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
48b0: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
48c0: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
48d0: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
48e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
48f0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
4900: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
4910: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
4920: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
4930: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
4940: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
4950: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
4960: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
4970: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
4980: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
4990: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
49a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
49b0: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
49c0: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
49d0: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
49e0: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
49f0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
4a00: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
4a10: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
4a20: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
4a30: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
4a40: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
4a50: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
4a60: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
4a70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
4a80: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
4a90: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
4aa0: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
4ab0: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
4ac0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
4ad0: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
4ae0: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
4af0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
4b00: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
4b10: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
4b20: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
4b30: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
4b40: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
4b50: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
4b60: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
4b70: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
4b80: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
4b90: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
4ba0: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
4bb0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
4bc0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
4bd0: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
4be0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
4bf0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
4c00: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
4c10: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
4c20: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
4c30: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
4c40: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4c50: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
4c60: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
4c70: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
4c80: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
4c90: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
4ca0: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
4cb0: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
4cc0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
4cd0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
4ce0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
4cf0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
4d00: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
4d10: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
4d20: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
4d30: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
4d40: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
4d50: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
4d60: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
4d70: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
4d80: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
4d90: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
4da0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
4db0: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
4dc0: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
4dd0: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
4de0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
4df0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
4e00: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
4e10: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
4e20: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
4e30: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
4e40: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
4e50: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
4e60: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
4e70: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
4e80: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
4e90: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
4ea0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
4eb0: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
4ec0: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
4ed0: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
4ee0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4ef0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
4f00: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
4f10: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
4f20: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
4f30: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
4f40: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
4f50: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
4f60: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
4f70: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4f80: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
4f90: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
4fa0: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
4fb0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
4fc0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
4fd0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
4fe0: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
4ff0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
5000: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
5010: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
5020: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
5030: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
5040: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
5050: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
5060: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5070: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
5080: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
5090: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
50a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
50b0: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
50c0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
50d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
50e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
50f0: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
5100: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5110: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
5120: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5130: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
5140: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
5150: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
5160: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5170: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
5180: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
5190: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
51a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
51b0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
51c0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
51d0: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
51e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
51f0: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
5200: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5210: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
5220: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5230: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
5240: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5250: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
5260: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5270: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
5280: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5290: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
52a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
52b0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
52c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
52d0: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
52e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
52f0: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
5300: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5310: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
5320: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5330: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
5340: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5350: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
5360: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5370: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
5380: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
5390: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
53a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53b0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
53c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
53d0: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
53e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
53f0: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
5400: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5410: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
5420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5430: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
5440: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5450: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
5460: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5470: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
5480: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5490: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
54a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54b0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
54c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
54d0: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
54e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
54f0: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
5500: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5510: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
5520: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5530: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
5540: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5550: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
5560: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5570: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
5580: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5590: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
55a0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
55b0: 52 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20  RR_DELETE_NOENT 
55c0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
55d0: 52 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64  RR | (23<<8)).#d
55e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
55f0: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
5600: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
5610: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
5620: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
5630: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
5640: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
5650: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
5660: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5670: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
5680: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
5690: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
56a0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
56b0: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
56c0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
56d0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
56e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
56f0: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c  TE_CANTOPEN_FULL
5700: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5710: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33  TE_CANTOPEN | (3
5720: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5730: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5740: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5750: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5760: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5770: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5780: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
5790: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
57a0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
57b0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
57c0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
57d0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
57e0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
57f0: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f  ne SQLITE_ABORT_
5800: 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20  ROLLBACK        
5810: 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20    (SQLITE_ABORT 
5820: 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a  | (2<<8))../*.**
5830: 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
5840: 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f   For File Open O
5850: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  perations.**.** 
5860: 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65 73  These bit values
5870: 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
5880: 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20  r use in the.** 
5890: 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
58a0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70   the [sqlite3_op
58b0: 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61  en_v2()] interfa
58c0: 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65  ce and.** in the
58d0: 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
58e0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  o the [sqlite3_v
58f0: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
5900: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
5910: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
5920: 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30  Y         0x0000
5930: 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0001  /* Ok for 
5940: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5950: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5960: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
5970: 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  TE        0x0000
5980: 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0002  /* Ok for 
5990: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
59a0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
59b0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20  ITE_OPEN_CREATE 
59c0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
59d0: 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0004  /* Ok for 
59e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
59f0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5a00: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
5a10: 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30  NCLOSE    0x0000
5a20: 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0008  /* VFS onl
5a30: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5a40: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
5a50: 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30 30  VE        0x0000
5a60: 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0010  /* VFS onl
5a70: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5a80: 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f  ITE_OPEN_AUTOPRO
5a90: 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30 30  XY        0x0000
5aa0: 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0020  /* VFS onl
5ab0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5ac0: 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20  ITE_OPEN_URI    
5ad0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5ae0: 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0040  /* Ok for 
5af0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5b00: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5b10: 49 54 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20  ITE_OPEN_MEMORY 
5b20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5b30: 30 30 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0080  /* Ok for 
5b40: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5b50: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5b60: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
5b70: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5b80: 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0100  /* VFS onl
5b90: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5ba0: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42  ITE_OPEN_TEMP_DB
5bb0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5bc0: 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0200  /* VFS onl
5bd0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5be0: 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45  ITE_OPEN_TRANSIE
5bf0: 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30 30  NT_DB     0x0000
5c00: 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0400  /* VFS onl
5c10: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5c20: 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f  ITE_OPEN_MAIN_JO
5c30: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5c40: 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0800  /* VFS onl
5c50: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5c60: 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f  ITE_OPEN_TEMP_JO
5c70: 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30  URNAL     0x0000
5c80: 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  1000  /* VFS onl
5c90: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5ca0: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
5cb0: 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30 30  NAL       0x0000
5cc0: 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  2000  /* VFS onl
5cd0: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5ce0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
5cf0: 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30  JOURNAL   0x0000
5d00: 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  4000  /* VFS onl
5d10: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
5d20: 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
5d30: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5d40: 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  8000  /* Ok for 
5d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5d60: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5d70: 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
5d80: 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30 31  EX        0x0001
5d90: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
5da0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5db0: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5dc0: 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
5dd0: 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30 32  ACHE      0x0002
5de0: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
5df0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5e00: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5e10: 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
5e20: 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30 34  CACHE     0x0004
5e30: 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20  0000  /* Ok for 
5e40: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5e50: 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ) */.#define SQL
5e60: 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20  ITE_OPEN_WAL    
5e70: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 38            0x0008
5e80: 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c  0000  /* VFS onl
5e90: 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65  y */../* Reserve
5ea0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
5eb0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
5ec0: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
5ed0: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
5ee0: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
5ef0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
5f00: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
5f10: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
5f20: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
5f30: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
5f40: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
5f50: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
5f60: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  tor of these.** 
5f70: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
5f80: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
5f90: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
5fa0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5fb0: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5fc0: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5fd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5fe0: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5ff0: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
6000: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6010: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6020: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6030: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6040: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
6050: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6060: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
6070: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
6080: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
6090: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
60a0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
60b0: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
60c0: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
60d0: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
60e0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
60f0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6100: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6110: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6120: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6130: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6140: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
6150: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
6160: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
6170: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
6180: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
6190: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
61a0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
61b0: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
61c0: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
61d0: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
61e0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
61f0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6200: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6210: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6220: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6230: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
6240: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6250: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
6260: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
6270: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
6280: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
6290: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
62a0: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
62b0: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
62c0: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
62d0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
62e0: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
62f0: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
6300: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
6310: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
6320: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
6330: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
6340: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
6350: 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64  unchanged..*/.#d
6360: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6370: 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20 20  AP_ATOMIC       
6380: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6390: 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  0001.#define SQL
63a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
63b0: 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20 20  512             
63c0: 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65 66   0x00000002.#def
63d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
63e0: 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20 20  _ATOMIC1K       
63f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6400: 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  04.#define SQLIT
6410: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
6420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6430: 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69 6e  x00000008.#defin
6440: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6450: 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20 20  TOMIC4K         
6460: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
6470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6480: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20 20  IOCAP_ATOMIC8K  
6490: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
64a0: 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65 20  0000020.#define 
64b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
64c0: 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20 20  MIC16K          
64d0: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a 23      0x00000040.#
64e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
64f0: 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20 20  CAP_ATOMIC32K   
6500: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6510: 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53 51  00080.#define SQ
6520: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6530: 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20 20  C64K            
6540: 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64 65    0x00000100.#de
6550: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6560: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20 20  P_SAFE_APPEND   
6570: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6580: 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  200.#define SQLI
6590: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
65a0: 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 20  IAL             
65b0: 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66 69  0x00000400.#defi
65c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
65d0: 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e  UNDELETABLE_WHEN
65e0: 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38 30  _OPEN  0x0000080
65f0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6600: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
6610: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30 78  _OVERWRITE    0x
6620: 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20  00001000../*.** 
6630: 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c  CAPI3REF: File L
6640: 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a  ocking Levels.**
6650: 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
6660: 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74  one of these int
6670: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6680: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67  he second.** arg
6690: 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69  ument to calls i
66a0: 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78  t makes to the x
66b0: 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f  Lock() and xUnlo
66c0: 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20  ck() methods.** 
66d0: 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69  of an [sqlite3_i
66e0: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
66f0: 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t..*/.#define SQ
6700: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20  LITE_LOCK_NONE  
6710: 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e          0.#defin
6720: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48  e SQLITE_LOCK_SH
6730: 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23 64  ARED        1.#d
6740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
6750: 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20 20  K_RESERVED      
6760: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
6770: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20  _LOCK_PENDING   
6780: 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
6790: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
67a0: 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a  IVE     4../*.**
67b0: 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68   CAPI3REF: Synch
67c0: 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20  ronization Type 
67d0: 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  Flags.**.** When
67e0: 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
67f0: 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68  the xSync() meth
6800: 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c  od of an.** [sql
6810: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
6820: 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73 20   object it uses 
6830: 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66  a combination of
6840: 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65  .** these intege
6850: 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20  r values as the 
6860: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e  second argument.
6870: 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20  .**.** When the 
6880: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6890: 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65  ONLY flag is use
68a0: 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  d, it means that
68b0: 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65   the.** sync ope
68c0: 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64  ration only need
68d0: 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20  s to flush data 
68e0: 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e  to mass storage.
68f0: 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72    Inode.** infor
6900: 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20  mation need not 
6910: 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74  be flushed. If t
6920: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6930: 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a  ts of the flag.*
6940: 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  * equal SQLITE_S
6950: 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74  YNC_NORMAL, that
6960: 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f   means to use no
6970: 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d  rmal fsync() sem
6980: 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68  antics..** If th
6990: 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74  e lower four bit
69a0: 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53  s equal SQLITE_S
69b0: 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d  YNC_FULL, that m
69c0: 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d  eans.** to use M
69d0: 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75  ac OS X style fu
69e0: 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f  llsync instead o
69f0: 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a  f fsync()..**.**
6a00: 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20   Do not confuse 
6a10: 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  the SQLITE_SYNC_
6a20: 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54  NORMAL and SQLIT
6a30: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67  E_SYNC_FULL flag
6a40: 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50  s.** with the [P
6a50: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6a60: 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50  s]=NORMAL and [P
6a70: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
6a80: 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69  s]=FULL.** setti
6a90: 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68  ngs.  The [synch
6aa0: 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64  ronous pragma] d
6ab0: 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63  etermines when c
6ac0: 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  alls to the.** x
6ad0: 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20  Sync VFS method 
6ae0: 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65  occur and applie
6af0: 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f  s uniformly acro
6b00: 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73  ss all platforms
6b10: 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  ..** The SQLITE_
6b20: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
6b30: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
6b40: 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65   flags determine
6b50: 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69   how.** energeti
6b60: 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72  c or rigorous or
6b70: 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79   forceful the sy
6b80: 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72  nc operations ar
6b90: 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61  e and.** only ma
6ba0: 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65 20  ke a difference 
6bb0: 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74  on Mac OSX for t
6bc0: 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74  he default SQLit
6bd0: 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72  e code..** (Thir
6be0: 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c  d-party VFS impl
6bf0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68  ementations migh
6c00: 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20  t also make the 
6c10: 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62  distinction.** b
6c20: 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59  etween SQLITE_SY
6c30: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6c40: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20  LITE_SYNC_FULL, 
6c50: 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a  but among the.**
6c60: 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
6c70: 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70  ms natively supp
6c80: 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c  orted by SQLite,
6c90: 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a   only Mac OSX.**
6ca0: 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68 65   cares about the
6cb0: 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f   difference.).*/
6cc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6cd0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20  SYNC_NORMAL     
6ce0: 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66 69     0x00002.#defi
6cf0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  ne SQLITE_SYNC_F
6d00: 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78 30  ULL          0x0
6d10: 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c  0003.#define SQL
6d20: 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c  ITE_SYNC_DATAONL
6d30: 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a  Y      0x00010..
6d40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6d50: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65  OS Interface Ope
6d60: 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a  n File Handle.**
6d70: 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f  .** An [sqlite3_
6d80: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70  file] object rep
6d90: 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20  resents an open 
6da0: 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20  file in the .** 
6db0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f  [sqlite3_vfs | O
6dc0: 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65  S interface laye
6dd0: 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20  r].  Individual 
6de0: 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  OS interface.** 
6df0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
6e00: 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20  will.** want to 
6e10: 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62  subclass this ob
6e20: 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e  ject by appendin
6e30: 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65  g additional fie
6e40: 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72  lds.** for their
6e50: 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70   own use.  The p
6e60: 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73  Methods entry is
6e70: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
6e80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
6e90: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
6ea0: 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74  that defines met
6eb0: 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d  hods for perform
6ec0: 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61  ing.** I/O opera
6ed0: 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65  tions on the ope
6ee0: 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64  n file..*/.typed
6ef0: 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
6f00: 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66  3_file sqlite3_f
6f10: 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ile;.struct sqli
6f20: 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e  te3_file {.  con
6f30: 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  st struct sqlite
6f40: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d  3_io_methods *pM
6f50: 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68  ethods;  /* Meth
6f60: 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20  ods for an open 
6f70: 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  file */.};../*.*
6f80: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
6f90: 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56 69  nterface File Vi
6fa0: 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62  rtual Methods Ob
6fb0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79  ject.**.** Every
6fc0: 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20   file opened by 
6fd0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
6fe0: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70  .xOpen] method p
6ff0: 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b  opulates an.** [
7000: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7010: 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63  ject (or, more c
7020: 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c  ommonly, a subcl
7030: 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ass of the.** [s
7040: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a  qlite3_file] obj
7050: 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ect) with a poin
7060: 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e  ter to an instan
7070: 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63  ce of this objec
7080: 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
7090: 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65  t defines the me
70a0: 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65  thods used to pe
70b0: 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70  rform various op
70c0: 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69  erations.** agai
70d0: 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c  nst the open fil
70e0: 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62 79  e represented by
70f0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7100: 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a  le] object..**.*
7110: 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * If the [sqlite
7120: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
7130: 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71 6c  hod sets the sql
7140: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
7150: 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74  ds element .** t
7160: 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  o a non-NULL poi
7170: 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73  nter, then the s
7180: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7190: 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a  s.xClose method.
71a0: 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65  ** may be invoke
71b0: 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73  d even if the [s
71c0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
71d0: 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74 20  ] reported that 
71e0: 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a  it failed.  The.
71f0: 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70  ** only way to p
7200: 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f  revent a call to
7210: 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e   xClose followin
7220: 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69  g a failed [sqli
7230: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a  te3_vfs.xOpen].*
7240: 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71  * is for the [sq
7250: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
7260: 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69   to set the sqli
7270: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
7280: 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20  s element.** to 
7290: 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  NULL..**.** The 
72a0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
72b0: 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f  o xSync may be o
72c0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59  ne of [SQLITE_SY
72d0: 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a  NC_NORMAL] or.**
72e0: 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55   [SQLITE_SYNC_FU
72f0: 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20  LL].  The first 
7300: 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f  choice is the no
7310: 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  rmal fsync()..**
7320: 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69   The second choi
7330: 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58  ce is a Mac OS X
7340: 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e   style fullsync.
7350: 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59    The [SQLITE_SY
7360: 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20  NC_DATAONLY].** 
7370: 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64  flag may be ORed
7380: 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20   in to indicate 
7390: 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61  that only the da
73a0: 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a  ta of the file.*
73b0: 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e  * and not its in
73c0: 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20  ode needs to be 
73d0: 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  synced..**.** Th
73e0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
73f0: 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20   to xLock() and 
7400: 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e  xUnlock() are on
7410: 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  e of.** <ul>.** 
7420: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  <li> [SQLITE_LOC
7430: 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e  K_NONE],.** <li>
7440: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
7450: 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  ARED],.** <li> [
7460: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
7470: 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  RVED],.** <li> [
7480: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44  SQLITE_LOCK_PEND
7490: 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  ING], or.** <li>
74a0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58   [SQLITE_LOCK_EX
74b0: 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75  CLUSIVE]..** </u
74c0: 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e  l>.** xLock() in
74d0: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
74e0: 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72  . xUnlock() decr
74f0: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a  eases the lock..
7500: 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65 73  ** The xCheckRes
7510: 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68  ervedLock() meth
7520: 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  od checks whethe
7530: 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  r any database c
7540: 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69  onnection,.** ei
7550: 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f  ther in this pro
7560: 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20  cess or in some 
7570: 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69  other process, i
7580: 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45  s holding a RESE
7590: 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47  RVED,.** PENDING
75a0: 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c  , or EXCLUSIVE l
75b0: 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e  ock on the file.
75c0: 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72 75    It returns tru
75d0: 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c  e.** if such a l
75e0: 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66  ock exists and f
75f0: 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a  alse otherwise..
7600: 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43  **.** The xFileC
7610: 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20  ontrol() method 
7620: 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74  is a generic int
7630: 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f  erface that allo
7640: 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53  ws custom.** VFS
7650: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7660: 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e   to directly con
7670: 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c  trol an open fil
7680: 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  e using the.** [
7690: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
76a0: 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63  trol()] interfac
76b0: 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22  e.  The second "
76c0: 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20  op" argument is 
76d0: 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70  an.** integer op
76e0: 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72 64  code.  The third
76f0: 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67   argument is a g
7700: 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69  eneric pointer i
7710: 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f  ntended to.** po
7720: 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74 75  int to a structu
7730: 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74  re that may cont
7740: 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  ain arguments or
7750: 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68 20   space in which 
7760: 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75  to.** write retu
7770: 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65  rn values.  Pote
7780: 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78  ntial uses for x
7790: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69  FileControl() mi
77a0: 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69  ght be.** functi
77b0: 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c  ons to enable bl
77c0: 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74  ocking locks wit
77d0: 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63  h timeouts, to c
77e0: 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63  hange the.** loc
77f0: 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28 66  king strategy (f
7800: 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73  or example to us
7810: 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73  e dot-file locks
7820: 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a  ), to inquire.**
7830: 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74 75   about the statu
7840: 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20  s of a lock, or 
7850: 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c  to break stale l
7860: 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74  ocks.  The SQLit
7870: 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76  e.** core reserv
7880: 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c  es all opcodes l
7890: 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72  ess than 100 for
78a0: 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a   its own use..**
78b0: 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c   A [SQLITE_FCNTL
78c0: 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73  _LOCKSTATE | lis
78d0: 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65  t of opcodes] le
78e0: 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61  ss than 100 is a
78f0: 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70  vailable..** App
7900: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64  lications that d
7910: 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78  efine a custom x
7920: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7930: 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70  od should use op
7940: 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72  codes.** greater
7950: 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f   than 100 to avo
7960: 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56  id conflicts.  V
7970: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
7980: 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74  ns should.** ret
7990: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  urn [SQLITE_NOTF
79a0: 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63  OUND] for file c
79b0: 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74  ontrol opcodes t
79c0: 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
79d0: 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a  ** recognize..**
79e0: 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53  .** The xSectorS
79f0: 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74  ize() method ret
7a00: 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20  urns the sector 
7a10: 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64  size of the.** d
7a20: 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72  evice that under
7a30: 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20  lies the file.  
7a40: 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20  The sector size 
7a50: 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75  is the.** minimu
7a60: 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e  m write that can
7a70: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69   be performed wi
7a80: 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67  thout disturbing
7a90: 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20  .** other bytes 
7aa0: 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  in the file.  Th
7ab0: 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  e xDeviceCharact
7ac0: 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65  eristics().** me
7ad0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62  thod returns a b
7ae0: 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69  it vector descri
7af0: 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f  bing behaviors o
7b00: 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79  f the.** underly
7b10: 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a  ing device:.**.*
7b20: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
7b30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7b40: 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  MIC].** <li> [SQ
7b50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7b60: 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C512].** <li> [S
7b70: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7b80: 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC1K].** <li> [S
7b90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7ba0: 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC2K].** <li> [S
7bb0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7bc0: 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC4K].** <li> [S
7bd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7be0: 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  IC8K].** <li> [S
7bf0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7c00: 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC16K].** <li> [
7c10: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7c20: 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC32K].** <li> 
7c30: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7c40: 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC64K].** <li>
7c50: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53   [SQLITE_IOCAP_S
7c60: 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c  AFE_APPEND].** <
7c70: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
7c80: 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a  P_SEQUENTIAL].**
7c90: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
7ca0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
7cb0: 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65  OMIC property me
7cc0: 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69  ans that all wri
7cd0: 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69  tes of.** any si
7ce0: 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  ze are atomic.  
7cf0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7d00: 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65  _ATOMICnnn value
7d10: 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77  s.** mean that w
7d20: 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20  rites of blocks 
7d30: 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74  that are nnn byt
7d40: 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a  es in size and.*
7d50: 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f  * are aligned to
7d60: 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63   an address whic
7d70: 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  h is an integer 
7d80: 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e  multiple of.** n
7d90: 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20  nn are atomic.  
7da0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
7db0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c  _SAFE_APPEND val
7dc0: 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74  ue means.** that
7dd0: 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70   when data is ap
7de0: 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65  pended to a file
7df0: 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70  , the data is ap
7e00: 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20  pended.** first 
7e10: 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  then the size of
7e20: 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74   the file is ext
7e30: 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65  ended, never the
7e40: 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72   other.** way ar
7e50: 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54  ound.  The SQLIT
7e60: 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49  E_IOCAP_SEQUENTI
7e70: 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  AL property mean
7e80: 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d  s that.** inform
7e90: 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e  ation is written
7ea0: 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20   to disk in the 
7eb0: 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61  same order as ca
7ec0: 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65  lls.** to xWrite
7ed0: 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65  ()..**.** If xRe
7ee0: 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c  ad() returns SQL
7ef0: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
7f00: 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73  READ it must als
7f10: 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65  o fill.** in the
7f20: 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73   unread portions
7f30: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77   of the buffer w
7f40: 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46  ith zeros.  A VF
7f50: 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20  S that.** fails 
7f60: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
7f70: 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73  rt reads might s
7f80: 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f  eem to work.  Ho
7f90: 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72  wever,.** failur
7fa0: 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  e to zero-fill s
7fb0: 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20  hort reads will 
7fc0: 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20  eventually lead 
7fd0: 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  to.** database c
7fe0: 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  orruption..*/.ty
7ff0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
8000: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
8010: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8020: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
8030: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a  e3_io_methods {.
8040: 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a    int iVersion;.
8050: 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28    int (*xClose)(
8060: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
8070: 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73    int (*xRead)(s
8080: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f  qlite3_file*, vo
8090: 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73  id*, int iAmt, s
80a0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
80b0: 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72  st);.  int (*xWr
80c0: 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ite)(sqlite3_fil
80d0: 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  e*, const void*,
80e0: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
80f0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
8100: 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61  .  int (*xTrunca
8110: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8120: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8130: 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a   size);.  int (*
8140: 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66  xSync)(sqlite3_f
8150: 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29  ile*, int flags)
8160: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53  ;.  int (*xFileS
8170: 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ize)(sqlite3_fil
8180: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
8190: 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74  4 *pSize);.  int
81a0: 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65   (*xLock)(sqlite
81b0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
81c0: 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28   int (*xUnlock)(
81d0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
81e0: 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68  nt);.  int (*xCh
81f0: 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29  eckReservedLock)
8200: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
8210: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
8220: 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74   int (*xFileCont
8230: 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  rol)(sqlite3_fil
8240: 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64  e*, int op, void
8250: 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28   *pArg);.  int (
8260: 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71  *xSectorSize)(sq
8270: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
8280: 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61  int (*xDeviceCha
8290: 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71  racteristics)(sq
82a0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
82b0: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
82c0: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
82d0: 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e  ersion 1 */.  in
82e0: 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c  t (*xShmMap)(sql
82f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8300: 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69  iPg, int pgsz, i
8310: 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c  nt, void volatil
8320: 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  e**);.  int (*xS
8330: 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  hmLock)(sqlite3_
8340: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65  file*, int offse
8350: 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c  t, int n, int fl
8360: 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78  ags);.  void (*x
8370: 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69  ShmBarrier)(sqli
8380: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
8390: 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73  t (*xShmUnmap)(s
83a0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
83b0: 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20  t deleteFlag);. 
83c0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
83d0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
83e0: 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f  version 2 */.  /
83f0: 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65 74  * Additional met
8400: 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64 65  hods may be adde
8410: 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
8420: 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a  ases */.};../*.*
8430: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61 6e  * CAPI3REF: Stan
8440: 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72 6f  dard File Contro
8450: 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  l Opcodes.**.** 
8460: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
8470: 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63 6f  nstants are opco
8480: 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69 6c  des for the xFil
8490: 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 0a  eControl method.
84a0: 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
84b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
84c0: 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74 68  bject and for th
84d0: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  e [sqlite3_file_
84e0: 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e  control()].** in
84f0: 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54  terface..**.** T
8500: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8510: 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63 6f  _LOCKSTATE] opco
8520: 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20 64  de is used for d
8530: 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a  ebugging.  This.
8540: 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73  ** opcode causes
8550: 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f   the xFileContro
8560: 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69 74  l method to writ
8570: 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74  e the current st
8580: 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f  ate of.** the lo
8590: 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c 49  ck (one of [SQLI
85a0: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b  TE_LOCK_NONE], [
85b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
85c0: 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ED],.** [SQLITE_
85d0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 20  LOCK_RESERVED], 
85e0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
85f0: 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  DING], or [SQLIT
8600: 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45  E_LOCK_EXCLUSIVE
8610: 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69 6e  ]).** into an in
8620: 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20 70  teger that the p
8630: 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  Arg argument poi
8640: 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61 70  nts to. This cap
8650: 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75 73  ability.** is us
8660: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
8670: 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73  g and only needs
8680: 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
8690: 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53   when SQLITE_TES
86a0: 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64 2e  T.** is defined.
86b0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
86c0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
86d0: 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68  IZE_HINT]].** Th
86e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
86f0: 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f 64  SIZE_HINT] opcod
8700: 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51 4c  e is used by SQL
8710: 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65 20  ite to give the 
8720: 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20 68  VFS.** layer a h
8730: 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67 65  int of how large
8740: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
8750: 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f 20  le will grow to 
8760: 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a 2a  be during the.**
8770: 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61 63   current transac
8780: 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e 74  tion.  This hint
8790: 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65   is not guarante
87a0: 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61 74  ed to be accurat
87b0: 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20 6f  e but it.** is o
87c0: 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68 65  ften close.  The
87d0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53 20   underlying VFS 
87e0: 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f 20  might choose to 
87f0: 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74 61  preallocate data
8800: 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70 61  base.** file spa
8810: 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69 73  ce based on this
8820: 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20 74   hint in order t
8830: 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74 6f  o help writes to
8840: 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   the database.**
8850: 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65 72   file run faster
8860: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
8870: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
8880: 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  _SIZE]].** The [
8890: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
88a0: 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20  NK_SIZE] opcode 
88b0: 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75 65  is used to reque
88c0: 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53 0a  st that the VFS.
88d0: 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74  ** extends and t
88e0: 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61 74  runcates the dat
88f0: 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68  abase file in ch
8900: 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73  unks of a size s
8910: 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74  pecified.** by t
8920: 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75  he user. The fou
8930: 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
8940: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8950: 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20  ntrol()] should 
8960: 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
8970: 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69 6e  integer (type in
8980: 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  t) containing th
8990: 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65  e new chunk-size
89a0: 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74   to use.** for t
89b0: 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74  he nominated dat
89c0: 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e  abase. Allocatin
89d0: 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  g database file 
89e0: 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a  space in large.*
89f0: 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d  * chunks (say 1M
8a00: 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61  B at a time), ma
8a10: 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79  y reduce file-sy
8a20: 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  stem fragmentati
8a30: 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76  on and.** improv
8a40: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e  e performance on
8a50: 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a   some systems..*
8a60: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
8a70: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
8a80: 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  NTER]].** The [S
8a90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45  QLITE_FCNTL_FILE
8aa0: 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64 65  _POINTER] opcode
8ab0: 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74 61   is used to obta
8ac0: 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  in a pointer.** 
8ad0: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
8ae0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73 73  file] object ass
8af0: 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 70  ociated with a p
8b00: 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62 61  articular databa
8b10: 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
8b20: 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c 69  .  See the [sqli
8b30: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8b40: 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  ()] documentatio
8b50: 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f  n for.** additio
8b60: 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
8b70: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8b80: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
8b90: 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68  MITTED]].** ^(Th
8ba0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8bb0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70  SYNC_OMITTED] op
8bc0: 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65  code is generate
8bd0: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a  d internally by.
8be0: 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65  ** SQLite and se
8bf0: 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20  nt to all VFSes 
8c00: 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61  in place of a ca
8c10: 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20  ll to the xSync 
8c20: 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74  method.** when t
8c30: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
8c40: 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47  ection has [PRAG
8c50: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20  MA synchronous] 
8c60: 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a  set to OFF.)^.**
8c70: 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65   Some specialize
8c80: 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69  d VFSes need thi
8c90: 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65  s signal in orde
8ca0: 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72  r to operate cor
8cb0: 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b  rectly.** when [
8cc0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
8cd0: 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63  us | PRAGMA sync
8ce0: 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20  hronous=OFF] is 
8cf0: 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a  set, but most .*
8d00: 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e  * VFSes do not n
8d10: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
8d20: 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e  and should silen
8d30: 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20  tly ignore this 
8d40: 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69  opcode..** Appli
8d50: 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e  cations should n
8d60: 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  ot call [sqlite3
8d70: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8d80: 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70   with this.** op
8d90: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
8da0: 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65   may disrupt the
8db0: 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68   operation of th
8dc0: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
8dd0: 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72  Ses.** that do r
8de0: 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a  equire it.  .**.
8df0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8e00: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52  FCNTL_WIN32_AV_R
8e10: 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  ETRY]].** ^The [
8e20: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
8e30: 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63  32_AV_RETRY] opc
8e40: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63  ode is used to c
8e50: 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74  onfigure automat
8e60: 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e  ic.** retry coun
8e70: 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73  ts and intervals
8e80: 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73   for certain dis
8e90: 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73  k I/O operations
8ea0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64   for the.** wind
8eb0: 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64  ows [VFS] in ord
8ec0: 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f  er to provide ro
8ed0: 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20  bustness in the 
8ee0: 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61  presence of.** a
8ef0: 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61  nti-virus progra
8f00: 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ms.  By default,
8f10: 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
8f20: 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65   will retry file
8f30: 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77   read,.** file w
8f40: 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64  rite, and file d
8f50: 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73  elete operations
8f60: 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c   up to 10 times,
8f70: 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a   with a delay.**
8f80: 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f   of 25 milliseco
8f90: 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66  nds before the f
8fa0: 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77  irst retry and w
8fb0: 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e  ith the delay in
8fc0: 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61  creasing.** by a
8fd0: 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20  n additional 25 
8fe0: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74  milliseconds wit
8ff0: 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e  h each subsequen
9000: 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a  t retry.  This.*
9010: 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20  * opcode allows 
9020: 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73  these two values
9030: 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64   (10 retries and
9040: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9050: 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f   of delay).** to
9060: 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54   be adjusted.  T
9070: 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68  he values are ch
9080: 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61  anged for all da
9090: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
90a0: 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65  ns.** within the
90b0: 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20   same process.  
90c0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
90d0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
90e0: 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20  array of two.** 
90f0: 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74  integers where t
9100: 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72  he first integer
9110: 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79   i the new retry
9120: 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73   count and the s
9130: 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72  econd.** integer
9140: 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20   is the delay.  
9150: 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65  If either intege
9160: 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
9170: 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a  hen the setting.
9180: 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  ** is not change
9190: 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68  d but instead th
91a0: 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66  e prior value of
91b0: 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73   that setting is
91c0: 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f   written.** into
91d0: 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79   the array entry
91e0: 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63  , allowing the c
91f0: 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74  urrent retry set
9200: 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69  tings to be.** i
9210: 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68  nterrogated.  Th
9220: 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65  e zDbName parame
9230: 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a  ter is ignored..
9240: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9250: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
9260: 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  _WAL]].** ^The [
9270: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9280: 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65  SIST_WAL] opcode
9290: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
92a0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
92b0: 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20  persistent [WAL 
92c0: 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f  | Write Ahead Lo
92d0: 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20  g] setting.  By 
92e0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78  default, the aux
92f0: 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20  iliary.** write 
9300: 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68  ahead log and sh
9310: 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65  ared memory file
9320: 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73  s used for trans
9330: 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a  action control.*
9340: 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  * are automatica
9350: 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e  lly deleted when
9360: 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e   the latest conn
9370: 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61  ection to the da
9380: 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73  tabase.** closes
9390: 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69  .  Setting persi
93a0: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63  stent WAL mode c
93b0: 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65  auses those file
93c0: 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74  s to persist aft
93d0: 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65  er.** close.  Pe
93e0: 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c  rsisting the fil
93f0: 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65  es is useful whe
9400: 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65  n other processe
9410: 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a  s that do not.**
9420: 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d   have write perm
9430: 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69  ission on the di
9440: 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69  rectory containi
9450: 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ng the database 
9460: 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20  file want.** to 
9470: 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73  read the databas
9480: 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57  e file, as the W
9490: 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65  AL and shared me
94a0: 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20  mory files must 
94b0: 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65  exist.** in orde
94c0: 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61  r for the databa
94d0: 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c  se to be readabl
94e0: 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  e.  The fourth p
94f0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9500: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9510: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9520: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9530: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
9540: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
9550: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
9560: 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69  to disable persi
9570: 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f  stent WAL mode o
9580: 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65  r 1 to enable pe
9590: 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20  rsistent.** WAL 
95a0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
95b0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
95c0: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
95d0: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
95e0: 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73  rent.** WAL pers
95f0: 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e  istence setting.
9600: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9610: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
9620: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a  AFE_OVERWRITE]].
9630: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
9640: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
9650: 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64  OVERWRITE] opcod
9660: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
9670: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
9680: 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77   persistent "pow
9690: 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65  ersafe-overwrite
96a0: 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74  " or "PSOW" sett
96b0: 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73  ing.  The PSOW s
96c0: 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d  etting.** determ
96d0: 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45  ines the [SQLITE
96e0: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
96f0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20  _OVERWRITE] bit 
9700: 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63  of the.** xDevic
9710: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
9720: 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f   methods. The fo
9730: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
9740: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  o.** [sqlite3_fi
9750: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f  le_control()] fo
9760: 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68  r this opcode sh
9770: 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65  ould be a pointe
9780: 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e  r to an integer.
9790: 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72  .** That integer
97a0: 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
97b0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64   zero-damage mod
97c0: 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65  e or 1 to enable
97d0: 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20   zero-damage.** 
97e0: 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e  mode.  If the in
97f0: 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65  teger is -1, the
9800: 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74  n it is overwrit
9810: 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72  ten with the cur
9820: 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d  rent.** zero-dam
9830: 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67  age mode setting
9840: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9850: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
9860: 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  RITE]].** ^The [
9870: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
9880: 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69  RWRITE] opcode i
9890: 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  s invoked by SQL
98a0: 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e  ite after openin
98b0: 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61  g.** a write tra
98c0: 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69  nsaction to indi
98d0: 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73  cate that, unles
98e0: 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62  s it is rolled b
98f0: 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20  ack for some.** 
9900: 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69  reason, the enti
9910: 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  re database file
9920: 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69   will be overwri
9930: 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72  tten by the curr
9940: 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74  ent .** transact
9950: 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65  ion. This is use
9960: 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72  d by VACUUM oper
9970: 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ations..**.** <l
9980: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9990: 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54  _VFSNAME]].** ^T
99a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
99b0: 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65  _VFSNAME] opcode
99c0: 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
99d0: 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73  obtain the names
99e0: 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65   of.** all [VFSe
99f0: 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74  s] in the VFS st
9a00: 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20  ack.  The names 
9a10: 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73  are of all VFS s
9a20: 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  hims and the.** 
9a30: 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76  final bottom-lev
9a40: 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74  el VFS are writt
9a50: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
9a60: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
9a70: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
9a80: 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75  ()] and the resu
9a90: 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20  lt is stored in 
9aa0: 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62  the char* variab
9ab0: 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66  le.** that the f
9ac0: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
9ad0: 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  of [sqlite3_file
9ae0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e  _control()] poin
9af0: 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61  ts to..** The ca
9b00: 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69  ller is responsi
9b10: 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20  ble for freeing 
9b20: 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20  the memory when 
9b30: 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a  done.  As with.*
9b40: 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72  * all file-contr
9b50: 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72  ol actions, ther
9b60: 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65  e is no guarante
9b70: 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c  e that this will
9b80: 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20   actually.** do 
9b90: 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65  anything.  Calle
9ba0: 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61  rs should initia
9bb0: 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76  lize the char* v
9bc0: 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c  ariable to a NUL
9bd0: 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20  L.** pointer in 
9be0: 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63  case this file-c
9bf0: 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d  ontrol is not im
9c00: 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73  plemented.  This
9c10: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a   file-control.**
9c20: 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72   is intended for
9c30: 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20   diagnostic use 
9c40: 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  only..**.** <li>
9c50: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
9c60: 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e  RAGMA]].** ^When
9c70: 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20  ever a [PRAGMA] 
9c80: 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72  statement is par
9c90: 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f  sed, an [SQLITE_
9ca0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a  FCNTL_PRAGMA] .*
9cb0: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  * file control i
9cc0: 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70  s sent to the op
9cd0: 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  en [sqlite3_file
9ce0: 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70  ] object corresp
9cf0: 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65  onding.** to the
9d00: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
9d10: 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67  o which the prag
9d20: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66  ma statement ref
9d30: 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65  ers. ^The argume
9d40: 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51  nt.** to the [SQ
9d50: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
9d60: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
9d70: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a  is an array of.*
9d80: 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74  * pointers to st
9d90: 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69  rings (char**) i
9da0: 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f  n which the seco
9db0: 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68  nd element of th
9dc0: 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68  e array.** is th
9dd0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72  e name of the pr
9de0: 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69  agma and the thi
9df0: 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68  rd element is th
9e00: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  e argument to th
9e10: 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e  e.** pragma or N
9e20: 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d  ULL if the pragm
9e30: 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e  a has no argumen
9e40: 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  t.  ^The handler
9e50: 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49   for an.** [SQLI
9e60: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9e70: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61   file control ca
9e80: 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b  n optionally mak
9e90: 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d  e the first elem
9ea0: 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68  ent.** of the ch
9eb0: 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f  ar** argument po
9ec0: 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20  int to a string 
9ed0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
9ee0: 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29  qlite3_mprintf()
9ef0: 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69  ].** or the equi
9f00: 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20  valent and that 
9f10: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f  string will beco
9f20: 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  me the result of
9f30: 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a   the pragma or.*
9f40: 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  * the error mess
9f50: 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d  age if the pragm
9f60: 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65  a fails. ^If the
9f70: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  .** [SQLITE_FCNT
9f80: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
9f90: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b  ontrol returns [
9fa0: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d  SQLITE_NOTFOUND]
9fb0: 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a  , then normal .*
9fc0: 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65  * [PRAGMA] proce
9fd0: 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e  ssing continues.
9fe0: 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54    ^If the [SQLIT
9ff0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a  E_FCNTL_PRAGMA].
a000: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
a010: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
a020: 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61  OK], then the pa
a030: 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61  rser assumes tha
a040: 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73  t the.** VFS has
a050: 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41   handled the PRA
a060: 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74  GMA itself and t
a070: 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61  he parser genera
a080: 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70  tes a no-op.** p
a090: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
a0a0: 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  t.  ^If the [SQL
a0b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a0c0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
a0d0: 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65  eturns.** any re
a0e0: 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20  sult code other 
a0f0: 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  than [SQLITE_OK]
a100: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46   or [SQLITE_NOTF
a110: 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e  OUND], that mean
a120: 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46  s.** that the VF
a130: 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e  S encountered an
a140: 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e   error while han
a150: 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d  dling the [PRAGM
a160: 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f  A] and the.** co
a170: 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65  mpilation of the
a180: 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69   PRAGMA fails wi
a190: 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54  th an error.  ^T
a1a0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a1b0: 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65  _PRAGMA].** file
a1c0: 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20   control occurs 
a1d0: 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  at the beginning
a1e0: 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65   of pragma state
a1f0: 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e  ment analysis an
a200: 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62  d so.** it is ab
a210: 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62  le to override b
a220: 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d  uilt-in [PRAGMA]
a230: 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
a240: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
a250: 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45  FCNTL_BUSYHANDLE
a260: 52 5d 5d 0a 2a 2a 20 5e 54 68 69 73 20 66 69 6c  R]].** ^This fil
a270: 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65  e-control may be
a280: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a290: 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61  te on the databa
a2a0: 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a  se file handle.*
a2b0: 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20  * shortly after 
a2c0: 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  it is opened in 
a2d0: 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65  order to provide
a2e0: 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69   a custom VFS wi
a2f0: 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  th access.** to 
a300: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  the connections 
a310: 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c  busy-handler cal
a320: 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d  lback. The argum
a330: 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28  ent is of type (
a340: 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e  void **).** - an
a350: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76   array of two (v
a360: 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54  oid *) values. T
a370: 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a  he first (void *
a380: 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74  ) actually point
a390: 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69  s.** to a functi
a3a0: 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20  on of type (int 
a3b0: 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e  (*)(void *)). In
a3c0: 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65   order to invoke
a3d0: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
a3e0: 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72  .** busy-handler
a3f0: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
a400: 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65  should be invoke
a410: 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e  d with the secon
a420: 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a  d (void *) in.**
a430: 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68   the array as th
a440: 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e  e only argument.
a450: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e   If it returns n
a460: 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68  on-zero, then th
a470: 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73  e operation.** s
a480: 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64  hould be retried
a490: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
a4a0: 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d  zero, the custom
a4b0: 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e   VFS should aban
a4c0: 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  don the.** curre
a4d0: 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a  nt operation..**
a4e0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
a4f0: 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e  _FCNTL_TEMPFILEN
a500: 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63  AME]].** ^Applic
a510: 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65  ation can invoke
a520: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
a530: 6f 6c 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74  ol to have SQLit
a540: 65 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20  e generate a.** 
a550: 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61  temporary filena
a560: 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  me using the sam
a570: 65 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74  e algorithm that
a580: 20 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20   is followed to 
a590: 67 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70  generate.** temp
a5a0: 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20  orary filenames 
a5b0: 66 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20  for TEMP tables 
a5c0: 61 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e  and other intern
a5d0: 61 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a  al uses.  The.**
a5e0: 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
a5f0: 20 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69   be a char** whi
a600: 63 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65  ch will be fille
a610: 64 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e  d with the filen
a620: 61 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69  ame.** written i
a630: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
a640: 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
a650: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68  3_malloc()].  Th
a660: 65 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a  e caller should.
a670: 2a 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74  ** invoke [sqlit
a680: 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68  e3_free()] on th
a690: 65 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69  e result to avoi
a6a0: 64 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e  d a memory leak.
a6b0: 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .**.** </ul>.*/.
a6c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
a6d0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
a6e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
a6f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45  define SQLITE_GE
a700: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
a710: 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64              2.#d
a720: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54  efine SQLITE_SET
a730: 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20  _LOCKPROXYFILE  
a740: 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65             3.#de
a750: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54  fine SQLITE_LAST
a760: 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20  _ERRNO          
a770: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
a780: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
a790: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
a7a0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
a7b0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
a7c0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
a7d0: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
a7e0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
a7f0: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
a800: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
a810: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
a820: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
a830: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
a840: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
a850: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
a860: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
a870: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
a880: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
a890: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
a8a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
a8b0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
a8c0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
a8d0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
a8e0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
a8f0: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
a900: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
a910: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
a920: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
a930: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
a940: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
a950: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
a960: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
a970: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
a980: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a990: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
a9a0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
a9b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
a9c0: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
a9d0: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
a9e0: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
a9f0: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
aa00: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
aa10: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
aa20: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
aa30: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
aa40: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
aa50: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
aa60: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
aa70: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
aa80: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
aa90: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
aaa0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
aab0: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
aac0: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
aad0: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
aae0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
aaf0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
ab00: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
ab10: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
ab20: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
ab30: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
ab40: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
ab50: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
ab60: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
ab70: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
ab80: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
ab90: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
aba0: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
abb0: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
abc0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
abd0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
abe0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
abf0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
ac00: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
ac10: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
ac20: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
ac30: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
ac40: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
ac50: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
ac60: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
ac70: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
ac80: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
ac90: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
aca0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
acb0: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
acc0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
acd0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
ace0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
acf0: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
ad00: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
ad10: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
ad20: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
ad30: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
ad40: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
ad50: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
ad60: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
ad70: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
ad80: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
ad90: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
ada0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
adb0: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
adc0: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
add0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
ade0: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
adf0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
ae00: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
ae10: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
ae20: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
ae30: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
ae40: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
ae50: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
ae60: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
ae70: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
ae80: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
ae90: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
aea0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
aeb0: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
aec0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
aed0: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
aee0: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
aef0: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
af00: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
af10: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
af20: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
af30: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
af40: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
af50: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
af60: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
af70: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
af80: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
af90: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
afa0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
afb0: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
afc0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
afd0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
afe0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
aff0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
b000: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
b010: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
b020: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
b030: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
b040: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
b050: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
b060: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
b070: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
b080: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
b090: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
b0a0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
b0b0: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
b0c0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
b0d0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
b0e0: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
b0f0: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
b100: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
b110: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
b120: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
b130: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
b140: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
b150: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
b160: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
b170: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
b180: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
b190: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
b1a0: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
b1b0: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
b1c0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
b1d0: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
b1e0: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
b1f0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
b200: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
b210: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
b220: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
b230: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
b240: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
b250: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
b260: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
b270: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
b280: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
b290: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
b2a0: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
b2b0: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
b2c0: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
b2d0: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
b2e0: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
b2f0: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
b300: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
b310: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
b320: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
b330: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
b340: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
b350: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
b360: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
b370: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
b380: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
b390: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
b3a0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
b3b0: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
b3c0: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
b3d0: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
b3e0: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
b3f0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
b400: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
b410: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
b420: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
b430: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
b440: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
b450: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
b460: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
b470: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
b480: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
b490: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
b4a0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
b4b0: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
b4c0: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
b4d0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
b4e0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
b4f0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
b500: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
b510: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
b520: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
b530: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
b540: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
b550: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
b560: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
b570: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
b580: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
b590: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
b5a0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
b5b0: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
b5c0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
b5d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
b5e0: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
b5f0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
b600: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
b610: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
b620: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
b630: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
b640: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
b650: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
b660: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
b670: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
b680: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
b690: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
b6a0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
b6b0: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
b6c0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
b6d0: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
b6e0: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
b6f0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
b700: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
b710: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
b720: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
b730: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
b740: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
b750: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
b760: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
b770: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
b780: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
b790: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
b7a0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
b7b0: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
b7c0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
b7d0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
b7e0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
b7f0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
b800: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
b810: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
b820: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
b830: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
b840: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
b850: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
b860: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
b870: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
b880: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
b890: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
b8a0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
b8b0: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
b8c0: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
b8d0: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
b8e0: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
b8f0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
b900: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
b910: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
b920: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
b930: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
b940: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
b950: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
b960: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
b970: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
b980: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
b990: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
b9a0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
b9b0: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
b9c0: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
b9d0: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
b9e0: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
b9f0: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
ba00: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
ba10: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
ba20: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
ba30: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
ba40: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
ba50: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
ba60: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
ba70: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
ba80: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
ba90: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
baa0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
bab0: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
bac0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
bad0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
bae0: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
baf0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
bb00: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
bb10: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
bb20: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
bb30: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
bb40: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
bb50: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
bb60: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
bb70: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
bb80: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
bb90: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
bba0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
bbb0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
bbc0: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
bbd0: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
bbe0: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
bbf0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
bc00: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
bc10: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
bc20: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
bc30: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
bc40: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
bc50: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
bc60: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
bc70: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
bc80: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
bc90: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
bca0: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
bcb0: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
bcc0: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
bcd0: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
bce0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
bcf0: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
bd00: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
bd10: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
bd20: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
bd30: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
bd40: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
bd50: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
bd60: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
bd70: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
bd80: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
bd90: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
bda0: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
bdb0: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
bdc0: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
bdd0: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
bde0: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
bdf0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
be00: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
be10: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
be20: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
be30: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
be40: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
be50: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
be60: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
be70: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
be80: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
be90: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
bea0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
beb0: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
bec0: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
bed0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
bee0: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
bef0: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
bf00: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
bf10: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
bf20: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
bf30: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
bf40: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
bf50: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
bf60: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
bf70: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
bf80: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
bf90: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
bfa0: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
bfb0: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
bfc0: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
bfd0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
bfe0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
bff0: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
c000: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
c010: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
c020: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
c030: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
c040: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
c050: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
c060: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
c070: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
c080: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
c090: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
c0a0: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
c0b0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
c0c0: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
c0d0: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
c0e0: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
c0f0: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
c100: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
c110: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
c120: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
c130: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
c140: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
c150: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
c160: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
c170: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
c180: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
c190: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
c1a0: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
c1b0: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
c1c0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
c1d0: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
c1e0: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
c1f0: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
c200: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
c210: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
c220: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
c230: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
c240: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
c250: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
c260: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
c270: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
c280: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
c290: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
c2a0: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
c2b0: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
c2c0: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
c2d0: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
c2e0: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
c2f0: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
c300: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
c310: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
c320: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
c330: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
c340: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
c350: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
c360: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
c370: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
c380: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
c390: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
c3a0: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
c3b0: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
c3c0: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
c3d0: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
c3e0: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
c3f0: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
c400: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
c410: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
c420: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
c430: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
c440: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
c450: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
c460: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
c470: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
c480: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
c490: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
c4a0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
c4b0: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
c4c0: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
c4d0: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
c4e0: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
c4f0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
c500: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
c510: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
c520: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
c530: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
c540: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
c550: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
c560: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
c570: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
c580: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
c590: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
c5a0: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
c5b0: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
c5c0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
c5d0: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
c5e0: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
c5f0: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
c600: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
c610: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
c620: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
c630: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
c640: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
c650: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
c660: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
c670: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
c680: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
c690: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
c6a0: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
c6b0: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
c6c0: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
c6d0: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
c6e0: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
c6f0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
c700: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
c710: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
c720: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
c730: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
c740: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
c750: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
c760: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
c770: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
c780: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
c790: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
c7a0: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
c7b0: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
c7c0: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
c7d0: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
c7e0: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
c7f0: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
c800: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
c810: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
c820: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
c830: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
c840: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
c850: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
c860: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
c870: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
c880: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
c890: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
c8a0: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
c8b0: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
c8c0: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
c8d0: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
c8e0: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
c8f0: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
c900: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
c910: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
c920: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
c930: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
c940: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
c950: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
c960: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
c970: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
c980: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
c990: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
c9a0: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
c9b0: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
c9c0: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
c9d0: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
c9e0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
c9f0: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
ca00: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
ca10: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
ca20: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
ca30: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
ca40: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
ca50: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
ca60: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
ca70: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
ca80: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
ca90: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
caa0: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
cab0: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
cac0: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
cad0: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
cae0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
caf0: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
cb00: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
cb10: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
cb20: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
cb30: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
cb40: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
cb50: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
cb60: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
cb70: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
cb80: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
cb90: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
cba0: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
cbb0: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
cbc0: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
cbd0: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
cbe0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
cbf0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
cc00: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
cc10: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
cc20: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
cc30: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
cc40: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
cc50: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
cc60: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
cc70: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
cc80: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
cc90: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
cca0: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
ccb0: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
ccc0: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
ccd0: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
cce0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
ccf0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
cd00: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
cd10: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
cd20: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
cd30: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
cd40: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
cd50: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
cd60: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
cd70: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
cd80: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
cd90: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
cda0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
cdb0: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
cdc0: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
cdd0: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
cde0: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
cdf0: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
ce00: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
ce10: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
ce20: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
ce30: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
ce40: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
ce50: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
ce60: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
ce70: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ce80: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
ce90: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
cea0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
ceb0: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
cec0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
ced0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
cee0: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
cef0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
cf00: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
cf10: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
cf20: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
cf30: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
cf40: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
cf50: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
cf60: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
cf70: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
cf80: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
cf90: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
cfa0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
cfb0: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
cfc0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
cfd0: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
cfe0: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
cff0: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
d000: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
d010: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
d020: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d030: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
d040: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
d050: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
d060: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
d070: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
d080: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
d090: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
d0a0: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
d0b0: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
d0c0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
d0d0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
d0e0: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
d0f0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
d100: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
d110: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
d120: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
d130: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
d140: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
d150: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
d160: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
d170: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
d180: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
d190: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
d1a0: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
d1b0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
d1c0: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
d1d0: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
d1e0: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
d1f0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
d200: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
d210: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
d220: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
d230: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
d240: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
d250: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
d260: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
d270: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
d280: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
d290: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
d2a0: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
d2b0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
d2c0: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
d2d0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
d2e0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
d2f0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
d300: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
d310: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
d320: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
d330: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
d340: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
d350: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
d360: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
d370: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
d380: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
d390: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
d3a0: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
d3b0: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
d3c0: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
d3d0: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
d3e0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
d3f0: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
d400: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
d410: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
d420: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
d430: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
d440: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
d450: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
d460: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
d470: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
d480: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
d490: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
d4a0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
d4b0: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
d4c0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
d4d0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
d4e0: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
d4f0: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
d500: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
d510: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
d520: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
d530: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
d540: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
d550: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
d560: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
d570: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
d580: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
d590: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
d5a0: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
d5b0: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
d5c0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
d5d0: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
d5e0: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
d5f0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
d600: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
d610: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
d620: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
d630: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
d640: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
d650: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
d660: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
d670: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
d680: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
d690: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
d6a0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
d6b0: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
d6c0: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
d6d0: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
d6e0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
d6f0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
d700: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
d710: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
d720: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
d730: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
d740: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
d750: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
d760: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
d770: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
d780: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
d790: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
d7a0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
d7b0: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
d7c0: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
d7d0: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
d7e0: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
d7f0: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
d800: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
d810: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68   was given no th
d820: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
d830: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
d840: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
d850: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
d860: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
d870: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
d880: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
d890: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
d8a0: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
d8b0: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
d8c0: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
d8d0: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
d8e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
d8f0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
d900: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
d910: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
d920: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
d930: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
d940: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
d950: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
d960: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
d970: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
d980: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
d990: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
d9a0: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
d9b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
d9c0: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
d9d0: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
d9e0: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
d9f0: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
da00: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
da10: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
da20: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
da30: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
da40: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
da50: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
da60: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
da70: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
da80: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
da90: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
daa0: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
dab0: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
dac0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
dad0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
dae0: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
daf0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
db00: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
db10: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
db20: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
db30: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
db40: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
db50: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
db60: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
db70: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
db80: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
db90: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
dba0: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
dbb0: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
dbc0: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
dbd0: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
dbe0: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
dbf0: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
dc00: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
dc10: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
dc20: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
dc30: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
dc40: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
dc50: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
dc60: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
dc70: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
dc80: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
dc90: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
dca0: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
dcb0: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
dcc0: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
dcd0: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
dce0: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
dcf0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
dd00: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
dd10: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
dd20: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
dd30: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
dd40: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
dd50: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
dd60: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
dd70: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
dd80: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
dd90: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
dda0: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
ddb0: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
ddc0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ddd0: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
dde0: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
ddf0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
de00: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
de10: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
de20: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
de30: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
de40: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
de50: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
de60: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
de70: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
de80: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
de90: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
dea0: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
deb0: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
dec0: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
ded0: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
dee0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
def0: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
df00: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
df10: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
df20: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
df30: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
df40: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
df50: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
df60: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
df70: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
df80: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
df90: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
dfa0: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
dfb0: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
dfc0: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
dfd0: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
dfe0: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
dff0: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
e000: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e010: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
e020: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
e030: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e040: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
e050: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
e060: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
e070: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
e080: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
e090: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
e0a0: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
e0b0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e0c0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
e0d0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
e0e0: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
e0f0: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
e100: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
e110: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
e120: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
e130: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
e140: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
e150: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
e160: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
e170: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
e180: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
e190: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
e1a0: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
e1b0: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
e1c0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
e1d0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
e1e0: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
e1f0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
e200: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
e210: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
e220: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
e230: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
e240: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
e250: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
e260: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
e270: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
e280: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
e290: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
e2a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e2b0: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
e2c0: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
e2d0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
e2e0: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
e2f0: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
e300: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
e310: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
e320: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
e330: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
e340: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
e350: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
e360: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
e370: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
e380: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
e390: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
e3a0: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
e3b0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
e3c0: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
e3d0: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
e3e0: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
e3f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e400: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
e410: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
e420: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
e430: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
e440: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
e450: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
e460: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
e470: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
e480: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
e490: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
e4a0: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
e4b0: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
e4c0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
e4d0: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
e4e0: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
e4f0: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
e500: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
e510: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
e520: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
e530: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
e540: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
e550: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
e560: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
e570: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
e580: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
e590: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
e5a0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
e5b0: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
e5c0: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
e5d0: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
e5e0: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
e5f0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
e600: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
e610: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
e620: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
e630: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
e640: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
e650: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
e660: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
e670: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
e680: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
e690: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
e6a0: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
e6b0: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
e6c0: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
e6d0: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
e6e0: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
e6f0: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
e700: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
e710: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
e720: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
e730: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
e740: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
e750: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
e760: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
e770: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
e780: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
e790: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
e7a0: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
e7b0: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
e7c0: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
e7d0: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
e7e0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
e7f0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
e800: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
e810: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
e820: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
e830: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
e840: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
e850: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
e860: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
e870: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
e880: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
e890: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e8a0: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
e8b0: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
e8c0: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
e8d0: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
e8e0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
e8f0: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
e900: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
e910: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
e920: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
e930: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
e940: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
e950: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
e960: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
e970: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
e980: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
e990: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
e9a0: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
e9b0: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
e9c0: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
e9d0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
e9e0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
e9f0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
ea00: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
ea10: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
ea20: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
ea30: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
ea40: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
ea50: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
ea60: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
ea70: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
ea80: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
ea90: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
eaa0: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
eab0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
eac0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
ead0: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49  lize(void);.SQLI
eae0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
eaf0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
eb00: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
eb10: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
eb20: 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  t(void);.SQLITE_
eb30: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
eb40: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
eb50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
eb60: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
eb70: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
eb80: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
eb90: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
eba0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
ebb0: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
ebc0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
ebd0: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
ebe0: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
ebf0: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
ec00: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
ec10: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
ec20: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
ec30: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
ec40: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
ec50: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
ec60: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
ec70: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
ec80: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
ec90: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
eca0: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
ecb0: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
ecc0: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
ecd0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
ece0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
ecf0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
ed00: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
ed10: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
ed20: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
ed30: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
ed40: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
ed50: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
ed60: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
ed70: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
ed80: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
ed90: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
eda0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
edb0: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
edc0: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
edd0: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
ede0: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
edf0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
ee00: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
ee10: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
ee20: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ee30: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
ee40: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
ee50: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
ee60: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
ee70: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
ee80: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
ee90: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
eea0: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
eeb0: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
eec0: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
eed0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
eee0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
eef0: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
ef00: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
ef10: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
ef20: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
ef30: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
ef40: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
ef50: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
ef60: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
ef70: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
ef80: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
ef90: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
efa0: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
efb0: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
efc0: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
efd0: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
efe0: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
eff0: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
f000: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
f010: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
f020: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
f030: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
f040: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
f050: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
f060: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
f070: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
f080: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
f090: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
f0a0: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
f0b0: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
f0c0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
f0d0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
f0e0: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
f0f0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
f100: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
f110: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
f120: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
f130: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
f140: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
f150: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
f160: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
f170: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
f180: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
f190: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
f1a0: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
f1b0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
f1c0: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
f1d0: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
f1e0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
f1f0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
f200: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
f210: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
f220: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
f230: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
f240: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
f250: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
f260: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
f270: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
f280: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
f290: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
f2a0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
f2b0: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
f2c0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
f2d0: 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
f2e0: 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
f2f0: 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
f300: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
f310: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
f320: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
f330: 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
f340: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
f350: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
f360: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
f370: 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
f380: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
f390: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
f3a0: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
f3b0: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
f3c0: 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
f3d0: 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
f3e0: 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
f3f0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f   int sqlite3_db_
f400: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
f410: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
f420: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
f430: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
f440: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
f450: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
f460: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
f470: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
f480: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
f490: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
f4a0: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
f4b0: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
f4c0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
f4d0: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
f4e0: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
f4f0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
f500: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
f510: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
f520: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
f530: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
f540: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
f550: 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
f560: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f570: 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
f580: 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
f590: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
f5a0: 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
f5b0: 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
f5c0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
f5d0: 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
f5e0: 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
f5f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
f600: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
f610: 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
f620: 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
f630: 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
f640: 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
f650: 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
f660: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f670: 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
f680: 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
f690: 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
f6a0: 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
f6b0: 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
f6c0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
f6d0: 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
f6e0: 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
f6f0: 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
f700: 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
f710: 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
f720: 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
f730: 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
f740: 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
f750: 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
f760: 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
f770: 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
f780: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
f790: 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
f7a0: 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
f7b0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
f7c0: 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
f7d0: 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
f7e0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
f7f0: 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
f800: 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
f810: 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
f820: 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
f830: 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
f840: 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
f850: 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
f860: 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
f870: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
f880: 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
f890: 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
f8a0: 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
f8b0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
f8c0: 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
f8d0: 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
f8e0: 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
f8f0: 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
f900: 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
f910: 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
f920: 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
f930: 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
f940: 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
f950: 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
f960: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
f970: 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
f980: 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
f990: 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
f9a0: 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
f9b0: 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
f9c0: 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
f9d0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
f9e0: 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
f9f0: 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
fa00: 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
fa10: 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
fa20: 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
fa30: 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
fa40: 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
fa50: 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
fa60: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
fa70: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
fa80: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
fa90: 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
faa0: 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
fab0: 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
fac0: 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
fad0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
fae0: 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
faf0: 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
fb00: 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
fb10: 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
fb20: 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
fb30: 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
fb40: 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
fb50: 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
fb60: 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
fb70: 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
fb80: 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
fb90: 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
fba0: 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
fbb0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
fbc0: 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
fbd0: 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
fbe0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
fbf0: 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
fc00: 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
fc10: 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
fc20: 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
fc30: 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
fc40: 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
fc50: 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
fc60: 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
fc70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
fc80: 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
fc90: 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
fca0: 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
fcb0: 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
fcc0: 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
fcd0: 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
fce0: 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
fcf0: 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
fd00: 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
fd10: 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
fd20: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
fd30: 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
fd40: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
fd50: 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
fd60: 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
fd70: 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
fd80: 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
fd90: 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
fda0: 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
fdb0: 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
fdc0: 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
fdd0: 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
fde0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
fdf0: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
fe00: 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
fe10: 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
fe20: 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
fe30: 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
fe40: 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
fe50: 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
fe60: 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
fe70: 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
fe80: 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
fe90: 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
fea0: 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
feb0: 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
fec0: 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
fed0: 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
fee0: 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
fef0: 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
ff00: 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
ff10: 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
ff20: 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
ff30: 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
ff40: 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
ff50: 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
ff60: 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
ff70: 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
ff80: 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
ff90: 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
ffa0: 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
ffb0: 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
ffc0: 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
ffd0: 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
ffe0: 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
fff0: 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
10000 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
10010 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
10020 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
10030 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
10040 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
10050 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
10060 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
10070 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
10080 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
10090 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
100a0 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
100b0 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
100c0 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
100d0 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
100e0 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
100f0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
10100 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
10110 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
10120 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
10130 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
10140 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
10150 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
10160 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
10170 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
10180 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
10190 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
101a0 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
101b0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
101c0 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
101d0 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
101e0 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
101f0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
10200 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
10210 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
10220 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
10230 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
10240 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
10250 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
10260 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
10270 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
10280 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
10290 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
102a0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
102b0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
102c0 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
102d0 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
102e0 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
102f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
10300 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
10310 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
10320 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
10330 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
10340 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
10350 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
10360 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
10370 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
10380 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
10390 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
103a0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
103b0 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
103c0 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
103d0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
103e0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
103f0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
10400 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
10410 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
10420 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
10430 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
10440 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
10450 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
10460 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
10470 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
10480 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
10490 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
104a0 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
104b0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
104c0 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
104d0 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
104e0 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
104f0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
10500 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
10510 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
10520 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
10530 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
10540 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
10550 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
10560 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
10570 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
10580 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
10590 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
105a0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
105b0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
105c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
105d0 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
105e0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
105f0 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
10600 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
10610 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
10620 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
10630 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
10640 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
10650 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
10660 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
10670 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
10680 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
10690 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
106a0 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
106b0 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
106c0 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
106d0 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
106e0 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
106f0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
10700 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
10710 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
10720 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
10730 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
10740 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
10750 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
10760 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
10770 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
10780 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
10790 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
107a0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
107b0 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
107c0 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
107d0 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
107e0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
107f0 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
10800 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
10810 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
10820 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
10830 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
10840 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
10850 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
10860 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
10870 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
10880 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
10890 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
108a0 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
108b0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
108c0 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
108d0 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
108e0 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
108f0 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
10900 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
10910 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10920 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
10930 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
10940 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
10950 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
10960 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
10970 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
10980 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
10990 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
109a0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
109b0 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
109c0 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
109d0 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
109e0 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
109f0 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
10a00 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
10a10 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
10a20 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
10a30 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
10a40 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
10a50 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
10a60 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
10a70 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
10a80 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
10a90 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
10aa0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
10ab0 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
10ac0 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
10ad0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
10ae0 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
10af0 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
10b00 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
10b10 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
10b20 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
10b30 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
10b40 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
10b50 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
10b60 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
10b70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
10b80 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
10b90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
10ba0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
10bb0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
10bc0 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
10bd0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
10be0 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
10bf0 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
10c00 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
10c10 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
10c20 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
10c30 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
10c40 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
10c50 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
10c60 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
10c70 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
10c80 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
10c90 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
10ca0 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
10cb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10cc0 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
10cd0 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
10ce0 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
10cf0 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
10d00 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
10d10 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
10d20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
10d30 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
10d40 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
10d50 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
10d60 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
10d70 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
10d80 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
10d90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
10da0 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
10db0 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
10dc0 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
10dd0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
10de0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
10df0 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
10e00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
10e10 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
10e20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
10e30 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
10e40 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
10e50 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
10e60 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
10e70 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
10e80 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
10e90 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
10ea0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
10eb0 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
10ec0 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
10ed0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
10ee0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
10ef0 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
10f00 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
10f10 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
10f20 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
10f30 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
10f40 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
10f50 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
10f60 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
10f70 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
10f80 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10f90 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
10fa0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
10fb0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
10fc0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
10fd0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
10fe0 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
10ff0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
11000 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
11010 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
11020 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
11030 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
11040 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
11050 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
11060 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
11070 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
11080 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11090 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
110a0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
110b0 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a   ^SQLite makes.*
110c0 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  * its own privat
110d0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  e copy of the co
110e0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
110f0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11100 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  s] structure.** 
11110 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69  before the [sqli
11120 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  te3_config()] ca
11130 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e  ll returns.</dd>
11140 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11150 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
11160 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
11170 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
11180 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
11190 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
111a0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
111b0 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
111c0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
111d0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
111e0 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
111f0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
11200 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
11210 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
11220 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
11230 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
11240 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
11250 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
11260 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
11270 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
11280 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
11290 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
112a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
112b0 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
112c0 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
112d0 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
112e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
112f0 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
11300 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
11310 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
11320 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11330 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
11340 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
11350 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
11360 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
11370 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
11380 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
11390 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e   of type int, in
113a0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a  terpreted as a .
113b0 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63  ** boolean, whic
113c0 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
113d0 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
113e0 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
113f0 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74  llocation .** st
11400 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
11410 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
11420 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
11430 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  e disabled, the 
11440 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  .** following SQ
11450 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
11460 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
11470 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
11480 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
11490 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
114a0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
114b0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
114c0 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
114d0 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
114e0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
114f0 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
11500 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
11510 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
11520 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
11530 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
11540 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
11550 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
11560 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
11570 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
11580 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
11590 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
115a0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
115b0 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
115c0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
115d0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
115e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
115f0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
11600 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
11610 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
11620 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
11630 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
11640 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
11650 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
11660 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
11670 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
11680 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
11690 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
116a0 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
116b0 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
116c0 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
116d0 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
116e0 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
116f0 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
11700 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
11710 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
11720 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
11730 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
11740 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
11750 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
11760 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72  ).  The sz.** ar
11770 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
11780 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e   multiple of 16.
11790 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
117a0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
117b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
117c0 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
117d0 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
117e0 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
117f0 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
11800 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f  Lite will use no
11810 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73   more than two s
11820 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
11830 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
11840 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
11850 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65  t to twice the e
11860 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
11870 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
11880 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  s..** ^SQLite wi
11890 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65  ll never require
118a0 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
118b0 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
118c0 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
118d0 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
118e0 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74   size. ^If SQLit
118f0 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
11900 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
11910 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
11920 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
11930 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
11940 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
11950 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
11960 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
11970 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
11980 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
11990 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  eeded.</dd>.**.*
119a0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
119b0 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
119c0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
119d0 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
119e0 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
119f0 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
11a00 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
11a10 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
11a20 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
11a30 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
11a40 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
11a50 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
11a60 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
11a70 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
11a80 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
11a90 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
11aa0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
11ab0 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
11ac0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
11ad0 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
11ae0 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
11af0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
11b00 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  ption..** There 
11b10 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
11b20 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
11b30 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  on: A pointer to
11b40 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
11b50 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
11b60 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
11b70 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
11b80 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
11b90 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
11ba0 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
11bb0 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
11bc0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
11bd0 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
11be0 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
11bf0 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
11c00 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c   32768) plus a l
11c10 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20  ittle extra for 
11c20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
11c30 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20  der.  ^The page 
11c40 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32  header size is 2
11c50 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65  0 to 40 bytes de
11c60 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68  pending on.** th
11c70 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74  e host architect
11c80 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72  ure.  ^It is har
11c90 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
11ca0 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
11cb0 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20  ory,.** to make 
11cc0 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20  sz a little too 
11cd0 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73  large.  The firs
11ce0 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
11cf0 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
11d00 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
11d10 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
11d20 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
11d30 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
11d40 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
11d50 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72  vided by the fir
11d60 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
11d70 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65  atisfy its.** me
11d80 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74  mory needs for t
11d90 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73  he first N pages
11da0 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f   that it adds to
11db0 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64   cache.  ^If add
11dc0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
11dd0 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
11de0 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
11df0 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
11e00 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
11e10 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
11e20 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
11e30 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
11e40 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
11e50 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
11e60 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
11e70 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
11e80 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e  must.** be align
11e90 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
11ea0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
11eb0 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
11ec0 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  of SQLite.** wil
11ed0 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
11ee0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11ef0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
11f00 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11f10 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
11f20 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
11f30 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
11f40 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
11f50 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
11f60 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
11f70 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
11f80 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
11f90 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
11fa0 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
11fb0 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
11fc0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
11fd0 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
11fe0 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
11ff0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
12000 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
12010 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
12020 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
12030 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
12040 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
12050 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
12060 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
12070 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
12080 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
12090 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
120a0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
120b0 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
120c0 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
120d0 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
120e0 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
120f0 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
12100 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
12110 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
12120 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
12130 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
12140 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
12150 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
12160 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
12170 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
12180 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
12190 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
121a0 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
121b0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
121c0 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
121d0 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
121e0 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
121f0 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
12200 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
12210 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
12220 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12230 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
12240 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
12250 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
12260 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
12270 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
12280 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
12290 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
122a0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
122b0 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
122c0 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
122d0 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
122e0 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
122f0 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
12300 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
12310 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
12320 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
12330 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
12340 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12350 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
12360 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12370 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
12380 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
12390 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
123a0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
123b0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
123c0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
123d0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
123e0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
123f0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
12400 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
12410 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
12420 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
12430 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
12440 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
12450 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
12460 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
12470 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
12480 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
12490 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  f the.** content
124a0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
124b0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
124c0 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
124d0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
124e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
124f0 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
12500 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
12510 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
12520 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
12530 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
12540 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
12550 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
12560 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
12570 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
12580 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
12590 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
125a0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
125b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
125c0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
125d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
125e0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
125f0 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
12600 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
12610 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
12620 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
12630 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
12640 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
12650 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
12660 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
12670 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
12680 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
12690 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
126a0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
126b0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
126c0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
126d0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
126e0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
126f0 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
12700 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
12710 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
12720 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
12730 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
12740 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
12750 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
12760 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
12770 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
12780 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
12790 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
127a0 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
127b0 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
127c0 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
127d0 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
127e0 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
127f0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
12800 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
12810 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
12820 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
12830 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
12840 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
12850 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
12860 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
12870 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
12880 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
12890 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
128a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
128b0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
128c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
128d0 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
128e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
128f0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
12900 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
12910 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12920 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
12930 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
12940 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
12950 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
12960 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
12970 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
12980 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
12990 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
129a0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
129b0 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  or the lookaside
129c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
129d0 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61  r on each.** [da
129e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
129f0 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  n].  The first a
12a00 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
12a10 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
12a20 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
12a30 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
12a40 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
12a50 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
12a60 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
12a70 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12a80 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f  ion.)^  ^(This o
12a90 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
12aa0 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
12ab0 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
12ac0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
12ad0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
12ae0 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c  .** verb to [sql
12af0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
12b00 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
12b10 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
12b20 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
12b30 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
12b40 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
12b50 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
12b60 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12b70 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
12b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
12b90 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
12ba0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
12bb0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
12bc0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
12bd0 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
12be0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
12bf0 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
12c00 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
12c10 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
12c20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
12c30 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
12c40 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
12c50 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
12c60 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
12c70 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
12c80 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
12c90 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
12ca0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
12cb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12cc0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
12cd0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
12ce0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
12cf0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12d00 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
12d10 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
12d20 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
12d30 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
12d40 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
12d50 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
12d60 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
12d70 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
12d80 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
12d90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
12da0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
12db0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
12dc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
12dd0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
12de0 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
12df0 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
12e00 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
12e10 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
12e20 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74  guments: a point
12e30 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74  er to a.** funct
12e40 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20  ion with a call 
12e50 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69  signature of voi
12e60 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  d(*)(void*,int,c
12e70 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a  onst char*), .**
12e80 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74   and a pointer t
12e90 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20  o void. ^If the 
12ea0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
12eb0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74   is not NULL, it
12ec0 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62   is.** invoked b
12ed0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  y [sqlite3_log()
12ee0 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63  ] to process eac
12ef0 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e  h logging event.
12f00 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e    ^If the.** fun
12f10 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
12f20 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69   NULL, the [sqli
12f30 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72  te3_log()] inter
12f40 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e  face becomes a n
12f50 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f  o-op..** ^The vo
12f60 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  id pointer that 
12f70 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
12f80 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45  gument to SQLITE
12f90 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a  _CONFIG_LOG is.*
12fa0 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  * passed through
12fb0 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
12fc0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
12fd0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
12fe0 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
12ff0 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74  ction whenever t
13000 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  hat function is 
13010 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73  invoked.  ^The s
13020 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
13030 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72  to.** the logger
13040 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63   function is a c
13050 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74  opy of the first
13060 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
13070 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
13080 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  ** [sqlite3_log(
13090 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69  )] call and is i
130a0 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20  ntended to be a 
130b0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
130c0 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   an.** [extended
130d0 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20   result code].  
130e0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
130f0 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  eter passed to t
13100 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20  he logger is.** 
13110 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65  log message afte
13120 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61  r formatting via
13130 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
13140 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51  tf()]..** The SQ
13150 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74  Lite logging int
13160 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
13170 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67  entrant; the log
13180 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ger function.** 
13190 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
131a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
131b0 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20   not invoke any 
131c0 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
131d0 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d  ..** In a multi-
131e0 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
131f0 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63  tion, the applic
13200 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
13210 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
13220 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
13230 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  afe. </dd>.**.**
13240 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13250 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _URI]] <dt>SQLIT
13260 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20  E_CONFIG_URI.** 
13270 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e  <dd> This option
13280 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13290 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
132a0 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72   int. If non-zer
132b0 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68  o, then.** URI h
132c0 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
132d0 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20  lly enabled. If 
132e0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
132f0 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20   zero, then URI 
13300 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67  handling.** is g
13310 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
13320 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e  . If URI handlin
13330 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
13340 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
13350 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  ames.** passed t
13360 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
13370 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
13380 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  n_v2()], [sqlite
13390 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
133a0 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
133b0 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
133c0 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
133d0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
133e0 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
133f0 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
13400 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
13410 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
13420 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
13430 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
13440 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49  ion is opened. I
13450 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
13460 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
13470 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
13480 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
13490 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
134a0 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
134b0 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
134c0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
134d0 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
134e0 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55  d. By default, U
134f0 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
13500 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
13510 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
13520 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
13530 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
13540 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
13550 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
13560 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
13570 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13580 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
13590 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e  NDEX_SCAN]] <dt>
135a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
135b0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
135c0 4e 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f  N.** <dd> This o
135d0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
135e0 6e 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67  ngle integer arg
135f0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
13600 6e 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a  nterpreted as.**
13610 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72   a boolean in or
13620 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  der to enable or
13630 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
13640 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
13650 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c  ices for.** full
13660 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20   table scans in 
13670 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  the query optimi
13680 7a 65 72 2e 20 20 54 68 65 20 64 65 66 61 75 6c  zer.  The defaul
13690 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74  t setting is det
136a0 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68  ermined.** by th
136b0 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f  e [SQLITE_ALLOW_
136c0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
136d0 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  CAN] compile-tim
136e0 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20  e option, or is 
136f0 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20  "on".** if that 
13700 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
13710 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a  ion is omitted..
13720 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74  ** The ability t
13730 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73  o disable the us
13740 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e  e of covering in
13750 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74  dices for full t
13760 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73  able scans.** is
13770 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e   because some in
13780 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20  correctly coded 
13790 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69  legacy applicati
137a0 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e  ons might malfun
137b0 63 74 69 6f 6e 0a 2a 2a 20 6d 61 6c 66 75 6e 63  ction.** malfunc
137c0 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 6f 70  tion when the op
137d0 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73 20 65 6e  timization is en
137e0 61 62 6c 65 64 2e 20 20 50 72 6f 76 69 64 69 6e  abled.  Providin
137f0 67 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  g the ability to
13800 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74 68 65 20  .** disable the 
13810 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c  optimization all
13820 6f 77 73 20 74 68 65 20 6f 6c 64 65 72 2c 20 62  ows the older, b
13830 75 67 67 79 20 61 70 70 6c 69 63 61 74 69 6f 6e  uggy application
13840 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   code to work.**
13850 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 65 20   without change 
13860 65 76 65 6e 20 77 69 74 68 20 6e 65 77 65 72 20  even with newer 
13870 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
13880 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  te..**.** [[SQLI
13890 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
138a0 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ]] [[SQLITE_CONF
138b0 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a  IG_GETPCACHE]].*
138c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
138d0 46 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53  FIG_PCACHE and S
138e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
138f0 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54  PCACHE.** <dd> T
13900 68 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65  hese options are
13910 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68   obsolete and sh
13920 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
13930 20 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a   by new code..**
13940 20 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e   They are retain
13950 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
13960 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62   compatibility b
13970 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70  ut are now no-op
13980 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a  s..** </dl>.**.*
13990 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
139a0 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64  G_SQLLOG]].** <d
139b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
139c0 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68  SQLLOG.** <dd>Th
139d0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c  is option is onl
139e0 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 73  y available if s
139f0 71 6c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  qlite is compile
13a00 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
13a10 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c  LITE_ENABLE_SQLL
13a20 4f 47 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  OG pre-processor
13a30 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20   macro defined. 
13a40 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
13a50 6e 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20  nt should.** be 
13a60 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66  a pointer to a f
13a70 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
13a80 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
13a90 6c 69 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61  lite3*,const cha
13aa0 72 2a 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65  r*, int)..** The
13ab0 20 73 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62   second should b
13ac0 65 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a  e of type (void*
13ad0 29 2e 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  ). The callback 
13ae0 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68  is invoked by th
13af0 65 20 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20  e library.** in 
13b00 74 68 72 65 65 20 73 65 70 61 72 61 74 65 20 63  three separate c
13b10 69 72 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64  ircumstances, id
13b20 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20  entified by the 
13b30 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73 20  value passed as 
13b40 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
13b50 72 61 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20  rameter. If the 
13b60 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
13b70 20 69 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20   is 0, then the 
13b80 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13b90 69 6f 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73  ion.** passed as
13ba0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
13bb0 6d 65 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65  ment has just be
13bc0 65 6e 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74  en opened. The t
13bd0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  hird argument.**
13be0 20 70 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66   points to a buf
13bf0 66 65 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  fer containing t
13c00 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d  he name of the m
13c10 61 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c  ain database fil
13c20 65 2e 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75  e. If the.** fou
13c30 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  rth parameter is
13c40 20 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c   1, then the SQL
13c50 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
13c60 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
13c70 74 65 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f  ter.** points to
13c80 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65   has just been e
13c90 78 65 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20  xecuted. Or, if 
13ca0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
13cb0 65 74 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a  eter is 2, then.
13cc0 2a 2a 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  ** the connectio
13cd0 6e 20 62 65 69 6e 67 20 70 61 73 73 65 64 20 61  n being passed a
13ce0 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
13cf0 61 6d 65 74 65 72 20 69 73 20 62 65 69 6e 67 20  ameter is being 
13d00 63 6c 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74  closed. The.** t
13d10 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
13d20 73 20 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e  s passed NULL In
13d30 20 74 68 69 73 20 63 61 73 65 2e 0a 2a 2a 20 3c   this case..** <
13d40 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
13d50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
13d60 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
13d70 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
13d80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
13d90 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
13da0 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
13db0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13dc0 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
13dd0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
13de0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
13df0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
13e00 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
13e10 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
13e20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
13e30 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
13e40 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
13e50 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
13e60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
13e70 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
13e80 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
13e90 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
13ea0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
13eb0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
13ec0 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
13ed0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
13ee0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13ef0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
13f00 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
13f10 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
13f20 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
13f30 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13f40 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
13f50 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
13f60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
13f70 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
13f80 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
13f90 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
13fa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13fb0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
13fc0 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
13fd0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
13fe0 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
13ff0 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
14000 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
14010 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
14020 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
14030 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14040 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
14050 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
14060 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14070 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
14080 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
14090 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
140a0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
140b0 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
140c0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
140d0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
140e0 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
140f0 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
14100 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
14110 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
14120 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
14130 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
14140 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
14150 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
14160 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
14170 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
14180 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
14190 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
141a0 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
141b0 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
141c0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
141d0 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58  G_COVERING_INDEX
141e0 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74  _SCAN 20  /* int
141f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14200 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
14210 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53         21  /* xS
14220 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a  qllog, void* */.
14230 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
14240 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
14250 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69  tion Configurati
14260 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  on Options.**.**
14270 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
14280 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
14290 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
142a0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
142b0 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
142c0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65  passed as the se
142d0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
142e0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62   the [sqlite3_db
142f0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
14300 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
14310 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14320 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
14330 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
14340 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
14350 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
14360 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
14370 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
14380 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
14390 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
143a0 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
143b0 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
143c0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
143d0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
143e0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
143f0 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b   worked.  ^The [
14400 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
14410 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77  g()] interface w
14420 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20  ill return a.** 
14430 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
14440 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f  code] if a disco
14450 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70  ntinued or unsup
14460 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61  ported configura
14470 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69  tion option.** i
14480 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a  s invoked..**.**
14490 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c   <dl>.** <dt>SQL
144a0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
144b0 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
144c0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
144d0 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64   takes three add
144e0 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74  itional argument
144f0 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
14500 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73   the .** [lookas
14510 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
14520 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74  ator] configurat
14530 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74  ion for the [dat
14540 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14550 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  ]..** ^The first
14560 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74   argument (the t
14570 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
14580 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
14590 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20  nfig()] is a.** 
145a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
145b0 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73  ory buffer to us
145c0 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20  e for lookaside 
145d0 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20  memory..** ^The 
145e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61  first argument a
145f0 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f  fter the SQLITE_
14600 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
14610 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62  DE verb.** may b
14620 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20  e NULL in which 
14630 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c  case SQLite will
14640 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a   allocate the.**
14650 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
14660 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b  r itself using [
14670 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
14680 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ]. ^The second a
14690 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
146a0 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
146b0 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
146c0 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72  slot.  ^The thir
146d0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
146e0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
146f0 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20  lots.  The size 
14700 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e  of the buffer in
14710 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
14720 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61  ent must be grea
14730 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65  ter than.** or e
14740 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64  qual to the prod
14750 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e  uct of the secon
14760 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75  d and third argu
14770 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66  ments.  The buff
14780 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c  er.** must be al
14790 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
147a0 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49  te boundary.  ^I
147b0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
147c0 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49  ument to.** SQLI
147d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
147e0 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d  ASIDE is not a m
147f0 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74  ultiple of 8, it
14800 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a   is internally.*
14810 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74  * rounded down t
14820 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c  o the next small
14830 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38  er multiple of 8
14840 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69  .  ^(The lookasi
14850 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e  de memory.** con
14860 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61  figuration for a
14870 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
14880 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65  tion can only be
14890 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68   changed when th
148a0 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  at.** connection
148b0 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
148c0 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64  y using lookasid
148d0 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20  e memory, or in 
148e0 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77  other words.** w
148f0 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74  hen the "current
14900 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64   value" returned
14910 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
14920 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51  db_status](D,[SQ
14930 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
14940 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a  ASIDE],...) is z
14950 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  ero..** Any atte
14960 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68  mpt to change th
14970 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
14980 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ry configuration
14990 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a   when lookaside.
149a0 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20  ** memory is in 
149b0 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63  use leaves the c
149c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63  onfiguration unc
149d0 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72  hanged and retur
149e0 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  ns .** [SQLITE_B
149f0 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  USY].)^</dd>.**.
14a00 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
14a10 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
14a20 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  EY</dt>.** <dd> 
14a30 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
14a40 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
14a50 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e  r disable the en
14a60 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20  forcement of.** 
14a70 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e  [foreign key con
14a80 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72  straints].  Ther
14a90 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20  e should be two 
14aa0 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
14ab0 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  ents..** The fir
14ac0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
14ad0 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
14ae0 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
14af0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a  FK enforcement,.
14b00 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65  ** positive to e
14b10 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  nable FK enforce
14b20 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65  ment or negative
14b30 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66   to leave FK enf
14b40 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68  orcement.** unch
14b50 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f  anged.  The seco
14b60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
14b70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
14b80 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69  integer into whi
14b90 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e  ch.** is written
14ba0 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63   0 or 1 to indic
14bb0 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65  ate whether FK e
14bc0 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66  nforcement is of
14bd0 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f  f or on.** follo
14be0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
14bf0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
14c00 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
14c10 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
14c20 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
14c30 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
14c40 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
14c50 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
14c60 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53  /dd>.**.** <dt>S
14c70 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
14c80 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64  NABLE_TRIGGER</d
14c90 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
14ca0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20   option is used 
14cb0 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73  to enable or dis
14cc0 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49  able [CREATE TRI
14cd0 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d  GGER | triggers]
14ce0 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c  ..** There shoul
14cf0 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
14d00 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
14d10 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
14d20 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
14d30 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
14d40 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72   disable trigger
14d50 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  s,.** positive t
14d60 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72  o enable trigger
14d70 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f  s or negative to
14d80 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69   leave the setti
14d90 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  ng unchanged..**
14da0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
14db0 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
14dc0 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
14dd0 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
14de0 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
14df0 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
14e00 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72  ther triggers ar
14e10 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e  e disabled or en
14e20 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69  abled.** followi
14e30 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54  ng this call.  T
14e40 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
14e50 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c  ter may be a NUL
14e60 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a  L pointer, in.**
14e70 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20   which case the 
14e80 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20  trigger setting 
14e90 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20  is not reported 
14ea0 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  back. </dd>.**.*
14eb0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
14ec0 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
14ed0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
14ee0 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64     1001  /* void
14ef0 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
14f00 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
14f10 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59  NFIG_ENABLE_FKEY
14f20 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e       1002  /* in
14f30 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e  t int* */.#defin
14f40 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
14f50 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
14f60 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69    1003  /* int i
14f70 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt* */.../*.** C
14f80 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
14f90 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
14fa0 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
14fb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
14fc0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
14fd0 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74  ult_codes() rout
14fe0 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ine enables or d
14ff0 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b  isables the.** [
15000 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
15010 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f  codes] feature o
15020 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65  f SQLite. ^The e
15030 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a  xtended result.*
15040 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61  * codes are disa
15050 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20  bled by default 
15060 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63  for historical c
15070 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f  ompatibility..*/
15080 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
15090 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
150a0 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71  _result_codes(sq
150b0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66  lite3*, int onof
150c0 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  f);../*.** CAPI3
150d0 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74  REF: Last Insert
150e0 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61   Rowid.**.** ^Ea
150f0 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53  ch entry in an S
15100 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20  QLite table has 
15110 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
15120 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
15130 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
15140 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
15150 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69  "]. ^The rowid i
15160 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
15170 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
15180 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
15190 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
151a0 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
151b0 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
151c0 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
151d0 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
151e0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
151f0 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68  lumns. ^If.** th
15200 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
15210 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
15220 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
15230 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
15240 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
15250 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
15260 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rowid..**.** ^Th
15270 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
15280 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  ns the [rowid] o
15290 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
152a0 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20  t.** successful 
152b0 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68  [INSERT] into th
152c0 65 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20  e database from 
152d0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
152e0 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  nnection].** in 
152f0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
15300 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69  nt.  ^As of SQLi
15310 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37  te version 3.7.7
15320 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a  , this routines.
15330 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c  ** records the l
15340 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64  ast insert rowid
15350 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72   of both ordinar
15360 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69  y tables and [vi
15370 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a  rtual tables]..*
15380 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73  * ^If no success
15390 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a  ful [INSERT]s.**
153a0 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72   have ever occur
153b0 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61  red on that data
153c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
153d0 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65   zero is returne
153e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  d..**.** ^(If an
153f0 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
15400 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
15410 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76  r or within a [v
15420 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
15430 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
15440 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
15450 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
15460 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
15470 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e  ed.** row as lon
15480 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
15490 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
154a0 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e  e method is runn
154b0 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
154c0 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
154d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
154e0 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76  thod ends, the v
154f0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
15500 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
15510 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
15520 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
15530 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
15540 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20  irtual.** table 
15550 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a  method began.)^.
15560 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
15570 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
15580 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
15590 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
155a0 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
155b0 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
155c0 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
155d0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
155e0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
155f0 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
15600 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
15610 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
15620 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
15630 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
15640 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
15650 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
15660 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
15670 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
15680 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
15690 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
156a0 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
156b0 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
156c0 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
156d0 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
156e0 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
156f0 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
15700 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
15710 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
15720 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
15730 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
15740 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
15750 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
15760 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
15770 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
15780 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
15790 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
157a0 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
157b0 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
157c0 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
157d0 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
157e0 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
157f0 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
15800 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
15810 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
15820 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
15830 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
15840 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
15850 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
15860 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
15870 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
15880 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
15890 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
158a0 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
158b0 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
158c0 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
158d0 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
158e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
158f0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
15900 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
15910 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
15920 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
15930 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
15940 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
15950 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
15960 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
15970 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
15980 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
15990 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
159a0 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
159b0 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
159c0 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
159d0 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49  [rowid]..*/.SQLI
159e0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
159f0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
15a00 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
15a10 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
15a20 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
15a30 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
15a40 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
15a50 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
15a60 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
15a70 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
15a80 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
15a90 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
15aa0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
15ab0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
15ac0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
15ad0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
15ae0 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
15af0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
15b00 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
15b10 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
15b20 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
15b30 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
15b40 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
15b50 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
15b60 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
15b70 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
15b80 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
15b90 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
15ba0 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
15bb0 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
15bc0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
15bd0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
15be0 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
15bf0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
15c00 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
15c10 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
15c20 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
15c30 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
15c40 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
15c50 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
15c60 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
15c70 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
15c80 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
15c90 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
15ca0 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
15cb0 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
15cc0 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
15cd0 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
15ce0 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
15cf0 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
15d00 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
15d10 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
15d20 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
15d30 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
15d40 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
15d50 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
15d60 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
15d70 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
15d80 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
15d90 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
15da0 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
15db0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
15dc0 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
15dd0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
15de0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
15df0 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
15e00 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
15e10 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
15e20 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
15e30 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
15e40 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
15e50 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
15e60 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
15e70 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
15e80 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
15e90 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
15ea0 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
15eb0 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
15ec0 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
15ed0 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
15ee0 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
15ef0 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
15f00 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
15f10 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
15f20 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
15f30 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
15f40 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
15f50 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
15f60 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
15f70 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
15f80 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
15f90 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
15fa0 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
15fb0 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
15fc0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
15fd0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
15fe0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
15ff0 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
16000 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
16010 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
16020 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
16030 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
16040 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
16050 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
16060 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
16070 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
16080 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
16090 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
160a0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
160b0 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
160c0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
160d0 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
160e0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
160f0 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
16100 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
16110 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
16120 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
16130 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
16140 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
16150 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
16160 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
16170 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
16180 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
16190 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
161a0 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
161b0 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
161c0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
161d0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
161e0 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
161f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
16200 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
16210 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
16220 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
16230 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
16240 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
16250 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
16260 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
16270 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
16280 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
16290 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
162a0 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
162b0 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
162c0 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
162d0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
162e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
162f0 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
16300 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
16310 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
16320 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
16330 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
16340 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
16350 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
16360 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
16370 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
16380 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
16390 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
163a0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
163b0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
163c0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
163d0 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
163e0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
163f0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
16400 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
16410 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
16420 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
16430 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
16440 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
16450 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
16460 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
16470 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
16480 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
16490 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d  used by [INSERT]
164a0 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72  ,.** [UPDATE] or
164b0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
164c0 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
164d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
164e0 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
164f0 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20  .** ^(The count 
16500 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
16510 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
16520 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  s() includes all
16530 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d   changes.** from
16540 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49   all [CREATE TRI
16550 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20  GGER | trigger] 
16560 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61  contexts and cha
16570 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20  nges made by.** 
16580 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
16590 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a  ions]. However,.
165a0 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
165b0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
165c0 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
165d0 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45  plement [REPLACE
165e0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  ] constraints,.*
165f0 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
16600 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
16610 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42  ng, or [DROP TAB
16620 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20  LE] processing. 
16630 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f   The.** count do
16640 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72  es not include r
16650 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61  ows of views tha
16660 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45  t fire an [INSTE
16670 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a  AD OF trigger],.
16680 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65  ** though if the
16690 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
166a0 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ger makes change
166b0 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68  s of its own, th
166c0 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20  ose changes .** 
166d0 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a  are counted.)^.*
166e0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
166f0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66  otal_changes() f
16700 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74  unction counts t
16710 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f  he changes as so
16720 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61  on as.** the sta
16730 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
16740 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
16750 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
16760 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a  atement handle.*
16770 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  * is passed to [
16780 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
16790 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
167a0 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
167b0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
167c0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
167d0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
167e0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
167f0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
16800 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67  the [total_chang
16810 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
16820 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
16830 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
16840 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
16850 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
16860 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
16870 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
16880 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
16890 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
168a0 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
168b0 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
168c0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
168d0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51  eaningful..*/.SQ
168e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
168f0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
16900 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
16910 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49  *.** CAPI3REF: I
16920 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d  nterrupt A Long-
16930 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a  Running Query.**
16940 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
16950 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65  on causes any pe
16960 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f  nding database o
16970 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72  peration to abor
16980 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20  t and.** return 
16990 61 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20  at its earliest 
169a0 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69  opportunity. Thi
169b0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70  s routine is typ
169c0 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64  ically.** called
169d0 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20   in response to 
169e0 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75  a user action su
169f0 63 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22  ch as pressing "
16a00 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74  Cancel".** or Ct
16a10 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75  rl-C where the u
16a20 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67  ser wants a long
16a30 20 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e   query operation
16a40 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65   to halt.** imme
16a50 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  diately..**.** ^
16a60 49 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61  It is safe to ca
16a70 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ll this routine 
16a80 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69  from a thread di
16a90 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65  fferent from the
16aa0 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20  .** thread that 
16ab0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e  is currently run
16ac0 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
16ad0 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75  e operation.  Bu
16ae0 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73  t it.** is not s
16af0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
16b00 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20   routine with a 
16b10 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
16b20 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73  tion] that.** is
16b30 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74   closed or might
16b40 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71   close before sq
16b50 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
16b60 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  ) returns..**.**
16b70 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72   ^If an SQL oper
16b80 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65  ation is very ne
16b90 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74  arly finished at
16ba0 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a   the time when.*
16bb0 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  * sqlite3_interr
16bc0 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  upt() is called,
16bd0 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e   then it might n
16be0 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72  ot have an oppor
16bf0 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20  tunity.** to be 
16c00 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20  interrupted and 
16c10 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74  might continue t
16c20 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a  o completion..**
16c30 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72  .** ^An SQL oper
16c40 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e  ation that is in
16c50 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72  terrupted will r
16c60 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e  eturn [SQLITE_IN
16c70 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66  TERRUPT]..** ^If
16c80 20 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64   the interrupted
16c90 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
16ca0 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44  s an INSERT, UPD
16cb0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
16cc0 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65  * that is inside
16cd0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
16ce0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74  nsaction, then t
16cf0 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61  he entire transa
16d00 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65  ction.** will be
16d10 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74   rolled back aut
16d20 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a  omatically..**.*
16d30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
16d40 6e 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c  nterrupt(D) call
16d50 20 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e   is in effect un
16d60 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c  til all currentl
16d70 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  y running.** SQL
16d80 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b   statements on [
16d90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16da0 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e  ion] D complete.
16db0 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73    ^Any new SQL s
16dc0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61  tatements.** tha
16dd0 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66  t are started af
16de0 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ter the sqlite3_
16df0 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
16e00 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20   and before the 
16e10 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74  .** running stat
16e20 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a  ements reaches z
16e30 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70  ero are interrup
16e40 74 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68  ted as if they h
16e50 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69  ad been.** runni
16e60 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ng prior to the 
16e70 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
16e80 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20  t() call.  ^New 
16e90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
16ea0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
16eb0 65 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e  ed after the run
16ec0 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63  ning statement c
16ed0 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72  ount reaches zer
16ee0 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66  o are.** not eff
16ef0 65 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  ected by the sql
16f00 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
16f10 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
16f20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
16f30 74 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73  t(D) that occurs
16f40 20 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20   when there are 
16f50 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51  no running.** SQ
16f60 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20  L statements is 
16f70 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20  a no-op and has 
16f80 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c  no effect on SQL
16f90 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
16fa0 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
16fb0 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
16fc0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
16fd0 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  ll returns..**.*
16fe0 2a 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  * If the databas
16ff0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
17000 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  ses while [sqlit
17010 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a  e3_interrupt()].
17020 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  ** is running th
17030 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69  en bad things wi
17040 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e  ll likely happen
17050 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
17060 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74  void sqlite3_int
17070 65 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29  errupt(sqlite3*)
17080 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
17090 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
170a0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
170b0 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a   Is Complete.**.
170c0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
170d0 73 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72  s are useful dur
170e0 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65  ing command-line
170f0 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d   input to determ
17100 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75  ine if the.** cu
17110 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20  rrently entered 
17120 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f  text seems to fo
17130 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  rm a complete SQ
17140 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a  L statement or.*
17150 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  * if additional 
17160 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20  input is needed 
17170 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74  before sending t
17180 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20  he text into.** 
17190 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69  SQLite for parsi
171a0 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74  ng.  ^These rout
171b0 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66  ines return 1 if
171c0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
171d0 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20  g.** appears to 
171e0 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51  be a complete SQ
171f0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41  L statement.  ^A
17200 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75   statement is ju
17210 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  dged to be.** co
17220 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64  mplete if it end
17230 73 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c  s with a semicol
17240 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20  on token and is 
17250 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20  not a prefix of 
17260 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64  a.** well-formed
17270 20 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20   CREATE TRIGGER 
17280 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d  statement.  ^Sem
17290 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65  icolons that are
172a0 20 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e   embedded within
172b0 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72  .** string liter
172c0 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64  als or quoted id
172d0 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f  entifier names o
172e0 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e  r comments are n
172f0 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e  ot.** independen
17300 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61  t tokens (they a
17310 72 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74  re part of the t
17320 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68  oken in which th
17330 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64  ey are.** embedd
17340 65 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20  ed) and thus do 
17350 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73  not count as a s
17360 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61  tatement termina
17370 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63  tor.  ^Whitespac
17380 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74  e.** and comment
17390 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68  s that follow th
173a0 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f  e final semicolo
173b0 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a  n are ignored..*
173c0 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
173d0 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66  ines return 0 if
173e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
173f0 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  s incomplete.  ^
17400 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  If a.** memory a
17410 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c  llocation fails,
17420 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d   then SQLITE_NOM
17430 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  EM is returned..
17440 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
17450 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72  tines do not par
17460 73 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  se the SQL state
17470 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69  ments thus.** wi
17480 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79  ll not detect sy
17490 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f  ntactically inco
174a0 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a  rrect SQL..**.**
174b0 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73   ^(If SQLite has
174c0 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61   not been initia
174d0 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  lized using [sql
174e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
174f0 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20  )] prior .** to 
17500 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33  invoking sqlite3
17510 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68  _complete16() th
17520 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  en sqlite3_initi
17530 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
17540 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61  ed.** automatica
17550 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63  lly by sqlite3_c
17560 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66  omplete16().  If
17570 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61   that initializa
17580 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74  tion fails,.** t
17590 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76  hen the return v
175a0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
175b0 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77  3_complete16() w
175c0 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a  ill be non-zero.
175d0 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
175e0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
175f0 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73  the input SQL is
17600 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a   complete.)^.**.
17610 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20  ** The input to 
17620 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74  [sqlite3_complet
17630 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a  e()] must be a z
17640 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
17650 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a  * UTF-8 string..
17660 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20  **.** The input 
17670 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70  to [sqlite3_comp
17680 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62  lete16()] must b
17690 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
176a0 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74  ted.** UTF-16 st
176b0 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62  ring in native b
176c0 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51  yte order..*/.SQ
176d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
176e0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f  ite3_complete(co
176f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a  nst char *sql);.
17700 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
17710 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
17720 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  6(const void *sq
17730 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
17740 52 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20  REF: Register A 
17750 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64  Callback To Hand
17760 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45  le SQLITE_BUSY E
17770 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  rrors.**.** ^Thi
17780 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61  s routine sets a
17790 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
177a0 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  on that might be
177b0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65   invoked wheneve
177c0 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20  r.** an attempt 
177d0 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20  is made to open 
177e0 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
177f0 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68   that another th
17800 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65  read.** or proce
17810 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a  ss has locked..*
17820 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73  *.** ^If the bus
17830 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
17840 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  LL, then [SQLITE
17850 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
17860 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
17870 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
17880 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e  immediately upon
17890 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68   encountering th
178a0 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65  e lock.  ^If the
178b0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a   busy callback.*
178c0 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  * is not NULL, t
178d0 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  hen the callback
178e0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
178f0 64 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d  d with two argum
17900 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
17910 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
17920 74 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  to the busy hand
17930 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ler is a copy of
17940 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74   the void* point
17950 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74  er which.** is t
17960 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
17970 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73  t to sqlite3_bus
17980 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54  y_handler().  ^T
17990 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
179a0 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73  nt to.** the bus
179b0 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  y handler callba
179c0 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ck is the number
179d0 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74   of times that t
179e0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
179f0 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f  has.** been invo
17a00 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63  ked for this loc
17a10 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66  king event.  ^If
17a20 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c   the.** busy cal
17a30 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c  lback returns 0,
17a40 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f   then no additio
17a50 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65  nal attempts are
17a60 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65   made to.** acce
17a70 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
17a80 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  and [SQLITE_BUSY
17a90 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
17aa0 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72  RR_BLOCKED] is r
17ab0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  eturned..** ^If 
17ac0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
17ad0 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
17ae0 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65  hen another atte
17af0 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74  mpt.** is made t
17b00 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
17b10 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ase for reading 
17b20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
17b30 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
17b40 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
17b50 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
17b60 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
17b70 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
17b80 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
17b90 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
17ba0 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
17bb0 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
17bc0 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
17bd0 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
17be0 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
17bf0 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
17c00 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
17c10 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
17c20 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51  _BUSY].** or [SQ
17c30 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
17c40 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69  ED] instead of i
17c50 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79  nvoking the busy
17c60 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
17c70 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
17c80 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
17c90 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
17ca0 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
17cb0 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
17cc0 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
17cd0 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
17ce0 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
17cf0 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
17d00 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
17d10 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
17d20 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
17d30 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
17d40 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
17d50 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
17d60 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
17d70 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
17d80 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
17d90 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
17da0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
17db0 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
17dc0 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
17dd0 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
17de0 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
17df0 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
17e00 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
17e10 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
17e20 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
17e30 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
17e40 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
17e50 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
17e60 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
17e70 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
17e80 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
17e90 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
17ea0 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
17eb0 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
17ec0 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
17ed0 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
17ee0 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
17ef0 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
17f00 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
17f10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
17f20 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
17f30 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
17f40 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
17f50 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
17f60 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
17f70 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
17f80 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
17f90 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
17fa0 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
17fb0 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
17fc0 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
17fd0 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
17fe0 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
17ff0 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
18000 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
18010 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
18020 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
18030 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
18040 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
18050 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
18060 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
18070 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
18080 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
18090 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
180a0 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
180b0 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
180c0 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
180d0 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
180e0 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
180f0 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
18100 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
18110 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
18120 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
18130 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
18140 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
18150 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
18160 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
18170 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
18180 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
18190 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
181a0 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
181b0 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
181c0 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
181d0 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
181e0 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
181f0 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
18200 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
18210 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
18220 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
18230 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
18240 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
18250 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
18260 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
18270 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
18280 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
18290 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
182a0 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
182b0 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
182c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
182d0 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
182e0 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
182f0 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
18300 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
18310 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
18320 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
18330 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
18340 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65  .** will also se
18350 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62  t or clear the b
18360 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a  usy handler..**.
18370 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c  ** The busy call
18380 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20  back should not 
18390 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73  take any actions
183a0 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68   which modify th
183b0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
183c0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
183d0 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
183e0 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63  andler.  Any suc
183f0 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73  h actions.** res
18400 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  ult in undefined
18410 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a   behavior..** .*
18420 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72  * A busy handler
18430 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20   must not close 
18440 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
18450 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70  nection.** or [p
18460 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
18470 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  t] that invoked 
18480 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
18490 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
184a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
184b0 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33  _handler(sqlite3
184c0 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c  *, int(*)(void*,
184d0 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  int), void*);../
184e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
184f0 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75  et A Busy Timeou
18500 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  t.**.** ^This ro
18510 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71  utine sets a [sq
18520 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
18530 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65  er | busy handle
18540 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a  r] that sleeps.*
18550 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65  * for a specifie
18560 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65  d amount of time
18570 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73   when a table is
18580 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68   locked.  ^The h
18590 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73  andler.** will s
185a0 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69  leep multiple ti
185b0 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61  mes until at lea
185c0 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
185d0 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
185e0 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c  .** have accumul
185f0 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74  ated.  ^After at
18600 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c   least "ms" mill
18610 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
18620 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e  ping,.** the han
18630 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77  dler returns 0 w
18640 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c  hich causes [sql
18650 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20  ite3_step()] to 
18660 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54  return.** [SQLIT
18670 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
18680 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
18690 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  ]..**.** ^Callin
186a0 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  g this routine w
186b0 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20  ith an argument 
186c0 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75  less than or equ
186d0 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75  al to zero.** tu
186e0 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79  rns off all busy
186f0 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a   handlers..**.**
18700 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
18710 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
18720 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  sy handler for a
18730 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
18740 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18750 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76  ion] any any giv
18760 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61  en moment.  If a
18770 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64  nother busy hand
18780 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e  ler.** was defin
18790 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69  ed  (using [sqli
187a0 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
187b0 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61  ()]) prior to ca
187c0 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f  lling.** this ro
187d0 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65  utine, that othe
187e0 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69  r busy handler i
187f0 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a  s cleared.)^.*/.
18800 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
18810 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
18820 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  out(sqlite3*, in
18830 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  t ms);../*.** CA
18840 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65  PI3REF: Convenie
18850 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72  nce Routines For
18860 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73   Running Queries
18870 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61  .**.** This is a
18880 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
18890 65 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72  e that is preser
188a0 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64  ved for backward
188b0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
188c0 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20  .** Use of this 
188d0 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
188e0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a   recommended..**
188f0 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20  .** Definition: 
18900 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c  A <b>result tabl
18910 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20  e</b> is memory 
18920 64 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63  data structure c
18930 72 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a  reated by the.**
18940 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
18950 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ble()] interface
18960 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  .  A result tabl
18970 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a  e records the.**
18980 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20   complete query 
18990 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65  results from one
189a0 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73   or more queries
189b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ..**.** The tabl
189c0 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68  e conceptually h
189d0 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72  as a number of r
189e0 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e  ows and columns.
189f0 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e    But.** these n
18a00 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70  umbers are not p
18a10 61 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c  art of the resul
18a20 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20  t table itself. 
18a30 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72   These.** number
18a40 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73  s are obtained s
18a50 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20  eparately.  Let 
18a60 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20  N be the number 
18a70 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d  of rows.** and M
18a80 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
18a90 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a  f columns..**.**
18aa0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
18ab0 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
18ac0 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d  ointers to zero-
18ad0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
18ae0 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65   strings..** The
18af0 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65  re are (N+1)*M e
18b00 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61  lements in the a
18b10 72 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74  rray.  The first
18b20 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e   M pointers poin
18b30 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72  t.** to zero-ter
18b40 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
18b50 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68  that  contain th
18b60 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63  e names of the c
18b70 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72  olumns..** The r
18b80 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73  emaining entries
18b90 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75   all point to qu
18ba0 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55  ery results.  NU
18bb0 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74  LL values result
18bc0 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e  .** in NULL poin
18bd0 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72  ters.  All other
18be0 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74   values are in t
18bf0 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d  heir UTF-8 zero-
18c00 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
18c10 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74  ring representat
18c20 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20  ion as returned 
18c30 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
18c40 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a  mn_text()]..**.*
18c50 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
18c60 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f   might consist o
18c70 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65  f one or more me
18c80 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
18c90 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73  ..** It is not s
18ca0 61 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65  afe to pass a re
18cb0 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63  sult table direc
18cc0 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  tly to [sqlite3_
18cd0 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65  free()]..** A re
18ce0 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c  sult table shoul
18cf0 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  d be deallocated
18d00 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
18d10 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a  free_table()]..*
18d20 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61  *.** ^(As an exa
18d30 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75  mple of the resu
18d40 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c  lt table format,
18d50 20 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79   suppose a query
18d60 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73   result.** is as
18d70 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
18d80 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
18d90 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65  >.**        Name
18da0 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a          | Age.**
18db0 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d          --------
18dc0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a  ---------------.
18dd0 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20  **        Alice 
18de0 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20        | 43.**   
18df0 20 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20       Bob        
18e00 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20   | 28.**        
18e10 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31  Cindy       | 21
18e20 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
18e30 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
18e40 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75  ere are two colu
18e50 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68  mn (M==2) and th
18e60 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e  ree rows (N==3).
18e70 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65    Thus the.** re
18e80 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38  sult table has 8
18e90 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f   entries.  Suppo
18ea0 73 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  se the result ta
18eb0 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a  ble is stored.**
18ec0 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d   in an array nam
18ed0 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68  es azResult.  Th
18ee0 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64  en azResult hold
18ef0 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a  s this content:.
18f00 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
18f10 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
18f20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30    azResult&#91;0
18f30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20  ] = "Name";.**  
18f40 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
18f50 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a  91;1] = "Age";.*
18f60 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
18f70 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63  t&#91;2] = "Alic
18f80 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
18f90 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20  Result&#91;3] = 
18fa0 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  "43";.**        
18fb0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20  azResult&#91;4] 
18fc0 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20  = "Bob";.**     
18fd0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
18fe0 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20  5] = "28";.**   
18ff0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
19000 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a  1;6] = "Cindy";.
19010 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
19020 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22  lt&#91;7] = "21"
19030 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
19040 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
19050 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
19060 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69  t_table() functi
19070 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65  on evaluates one
19080 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69   or more.** semi
19090 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20  colon-separated 
190a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
190b0 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  n the zero-termi
190c0 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73  nated UTF-8.** s
190d0 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64  tring of its 2nd
190e0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72   parameter and r
190f0 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20  eturns a result 
19100 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20  table to the.** 
19110 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e  pointer given in
19120 20 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74   its 3rd paramet
19130 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  er..**.** After 
19140 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
19150 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74  has finished wit
19160 68 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  h the result fro
19170 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  m sqlite3_get_ta
19180 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73  ble(),.** it mus
19190 74 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c  t pass the resul
191a0 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20  t table pointer 
191b0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  to sqlite3_free_
191c0 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72  table() in order
191d0 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74   to.** release t
191e0 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77  he memory that w
191f0 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65  as malloced.  Be
19200 63 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79  cause of the way
19210 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19220 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65  _malloc()] happe
19230 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65  ns within sqlite
19240 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74  3_get_table(), t
19250 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75  he calling.** fu
19260 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  nction must not 
19270 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c  try to call [sql
19280 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72  ite3_free()] dir
19290 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20  ectly.  Only.** 
192a0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61  [sqlite3_free_ta
192b0 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74  ble()] is able t
192c0 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65  o release the me
192d0 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e  mory properly an
192e0 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  d safely..**.** 
192f0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
19300 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63  table() interfac
19310 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64  e is implemented
19320 20 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72   as a wrapper ar
19330 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
19340 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73  _exec()].  The s
19350 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
19360 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
19370 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a  not have access.
19380 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e  ** to any intern
19390 61 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72  al data structur
193a0 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49  es of SQLite.  I
193b0 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20  t uses only the 
193c0 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66  public.** interf
193d0 61 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65  ace defined here
193e0 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65  .  As a conseque
193f0 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74  nce, errors that
19400 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a   occur in the.**
19410 20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f   wrapper layer o
19420 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e  utside of the in
19430 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f  ternal [sqlite3_
19440 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65  exec()] call are
19450 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65   not.** reflecte
19460 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  d in subsequent 
19470 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
19480 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a  3_errcode()] or.
19490 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d  ** [sqlite3_errm
194a0 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  sg()]..*/.SQLITE
194b0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
194c0 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71  _get_table(.  sq
194d0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
194e0 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
194f0 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
19500 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
19510 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
19520 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63  evaluated */.  c
19530 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74  har ***pazResult
19540 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20  ,    /* Results 
19550 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a  of the query */.
19560 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20    int *pnRow,   
19570 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
19580 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73  r of result rows
19590 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
195a0 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e  .  int *pnColumn
195b0 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62  ,        /* Numb
195c0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c  er of result col
195d0 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72  umns written her
195e0 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a  e */.  char **pz
195f0 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20  Errmsg       /* 
19600 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65  Error msg writte
19610 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c  n here */.);.SQL
19620 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
19630 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
19640 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
19650 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19660 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
19670 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
19680 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
19690 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
196a0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
196b0 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
196c0 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
196d0 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
196e0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
196f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
19700 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
19710 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
19720 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
19730 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
19740 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
19750 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
19760 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
19770 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
19780 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
19790 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
197a0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
197b0 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
197c0 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
197d0 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
197e0 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
197f0 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
19800 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
19810 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
19820 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
19830 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
19840 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
19850 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
19860 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
19870 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
19880 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
19890 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
198a0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
198b0 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
198c0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
198d0 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
198e0 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
198f0 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
19900 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
19910 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
19920 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
19930 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
19940 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
19950 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
19960 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
19970 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
19980 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
19990 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
199a0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
199b0 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
199c0 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
199d0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
199e0 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
199f0 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
19a00 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
19a10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
19a20 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
19a30 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
19a40 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
19a50 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
19a60 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
19a70 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
19a80 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
19a90 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
19aa0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
19ab0 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
19ac0 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
19ad0 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
19ae0 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
19af0 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
19b00 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
19b10 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
19b20 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
19b30 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
19b40 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
19b50 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
19b60 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
19b70 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
19b80 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
19b90 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
19ba0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
19bb0 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
19bc0 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
19bd0 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
19be0 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
19bf0 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
19c00 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
19c10 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
19c20 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
19c30 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
19c40 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
19c50 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
19c60 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
19c70 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
19c80 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
19c90 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
19ca0 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
19cb0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
19cc0 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
19cd0 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
19ce0 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
19cf0 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
19d00 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
19d10 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
19d20 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
19d30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
19d40 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
19d50 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
19d60 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
19d70 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
19d80 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
19d90 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
19da0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
19db0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
19dc0 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
19dd0 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
19de0 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
19df0 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
19e00 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
19e10 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
19e20 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
19e30 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
19e40 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
19e50 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
19e60 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
19e70 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
19e80 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
19e90 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
19ea0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
19eb0 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
19ec0 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
19ed0 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
19ee0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
19ef0 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
19f00 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
19f10 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
19f20 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
19f30 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
19f40 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
19f50 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
19f60 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
19f70 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
19f80 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
19f90 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
19fa0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
19fb0 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
19fc0 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
19fd0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
19fe0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
19ff0 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1a000 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1a010 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1a020 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
1a030 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
1a040 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
1a050 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
1a060 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
1a070 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1a080 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
1a090 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
1a0a0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
1a0b0 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
1a0c0 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
1a0d0 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
1a0e0 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
1a0f0 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
1a100 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1a110 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1a120 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1a130 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
1a140 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
1a150 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1a160 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1a170 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
1a180 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
1a190 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
1a1a0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
1a1b0 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
1a1c0 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
1a1d0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1a1e0 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
1a1f0 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
1a200 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
1a210 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
1a220 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1a230 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
1a240 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
1a250 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
1a260 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
1a270 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
1a280 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
1a290 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
1a2a0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
1a2b0 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
1a2c0 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
1a2d0 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
1a2e0 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
1a2f0 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
1a300 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
1a310 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
1a320 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
1a330 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
1a340 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
1a350 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
1a360 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
1a370 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
1a380 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
1a390 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
1a3a0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
1a3b0 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
1a3c0 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
1a3d0 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
1a3e0 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
1a3f0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1a400 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
1a410 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
1a420 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
1a430 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
1a440 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1a450 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1a460 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1a470 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1a480 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1a490 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
1a4a0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
1a4b0 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
1a4c0 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
1a4d0 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
1a4e0 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
1a4f0 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
1a500 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
1a510 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
1a520 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
1a530 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
1a540 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
1a550 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
1a560 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
1a570 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
1a580 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
1a590 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
1a5a0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
1a5b0 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
1a5c0 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
1a5d0 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49  tring.)^.*/.SQLI
1a5e0 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
1a5f0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e  ite3_mprintf(con
1a600 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53  st char*,...);.S
1a610 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1a620 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1a630 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
1a640 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41  _list);.SQLITE_A
1a650 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
1a660 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  _snprintf(int,ch
1a670 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1a680 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50   ...);.SQLITE_AP
1a690 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1a6a0 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68  vsnprintf(int,ch
1a6b0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1a6c0 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a   va_list);../*.*
1a6d0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1a6e0 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75  ry Allocation Su
1a6f0 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68  bsystem.**.** Th
1a700 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73  e SQLite core us
1a710 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72  es these three r
1a720 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20  outines for all 
1a730 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e  of its own.** in
1a740 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c  ternal memory al
1a750 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20  location needs. 
1a760 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72  "Core" in the pr
1a770 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a  evious sentence.
1a780 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ** does not incl
1a790 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79  ude operating-sy
1a7a0 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46  stem specific VF
1a7b0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1a7c0 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77  .  The.** Window
1a7d0 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76  s VFS uses nativ
1a7e0 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66  e malloc() and f
1a7f0 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f  ree() for some o
1a800 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  perations..**.**
1a810 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61   ^The sqlite3_ma
1a820 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72  lloc() routine r
1a830 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1a840 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f   to a block.** o
1a850 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73  f memory at leas
1a860 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e  t N bytes in len
1a870 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20  gth, where N is 
1a880 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
1a890 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
1a8a0 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65  lloc() is unable
1a8b0 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69   to obtain suffi
1a8c0 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65  cient free.** me
1a8d0 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73  mory, it returns
1a8e0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1a8f0 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65    ^If the parame
1a900 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69  ter N to.** sqli
1a910 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1a920 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65  zero or negative
1a930 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61   then sqlite3_ma
1a940 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a  lloc() returns.*
1a950 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
1a960 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1a970 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1a980 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70  with a pointer p
1a990 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e  reviously return
1a9a0 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1a9b0 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
1a9c0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72  ite3_realloc() r
1a9d0 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d  eleases that mem
1a9e0 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69  ory so.** that i
1a9f0 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65  t might be reuse
1aa00 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  d.  ^The sqlite3
1aa10 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20  _free() routine 
1aa20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66  is.** a no-op if
1aa30 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1aa40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1aa50 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20   Passing a NULL 
1aa60 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71  pointer.** to sq
1aa70 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1aa80 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72  harmless.  After
1aa90 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65   being freed, me
1aaa0 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e  mory.** should n
1aab0 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e  either be read n
1aac0 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65  or written.  Eve
1aad0 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f  n reading previo
1aae0 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65  usly freed.** me
1aaf0 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c  mory might resul
1ab00 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74  t in a segmentat
1ab10 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68  ion fault or oth
1ab20 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e  er severe error.
1ab30 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75  .** Memory corru
1ab40 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74  ption, a segment
1ab50 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20  ation fault, or 
1ab60 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1ab70 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75  or.** might resu
1ab80 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72  lt if sqlite3_fr
1ab90 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  ee() is called w
1aba0 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70  ith a non-NULL p
1abb0 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77  ointer that.** w
1abc0 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20  as not obtained 
1abd0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c  from sqlite3_mal
1abe0 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1abf0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a  _realloc()..**.*
1ac00 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1ac10 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66  realloc() interf
1ac20 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ace attempts to 
1ac30 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f  resize a.** prio
1ac40 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  r memory allocat
1ac50 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61  ion to be at lea
1ac60 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72  st N bytes, wher
1ac70 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65  e N is the.** se
1ac80 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1ac90 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   The memory allo
1aca0 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73  cation to be res
1acb0 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73  ized is the firs
1acc0 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29  t.** parameter.)
1acd0 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74  ^ ^ If the first
1ace0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1acf0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
1ad00 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
1ad10 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65  nter then its be
1ad20 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69  havior is identi
1ad30 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  cal to calling.*
1ad40 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1ad50 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74  (N) where N is t
1ad60 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1ad70 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1ad80 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66  ealloc()..** ^If
1ad90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1ada0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1adb0 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65  _realloc() is ze
1adc0 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76  ro or.** negativ
1add0 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  e then the behav
1ade0 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74  ior is exactly t
1adf0 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69  he same as calli
1ae00 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72  ng.** sqlite3_fr
1ae10 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73  ee(P) where P is
1ae20 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1ae30 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1ae40 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73  realloc()..** ^s
1ae50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ae60 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1ae70 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61  er to a memory a
1ae80 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
1ae90 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1aea0 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c   in size or NULL
1aeb0 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d   if sufficient m
1aec0 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c  emory is unavail
1aed0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69  able..** ^If M i
1aee0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  s the size of th
1aef0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1af00 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d  on, then min(N,M
1af10 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68  ) bytes.** of th
1af20 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1af30 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e  on are copied in
1af40 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67  to the beginning
1af50 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72   of buffer retur
1af60 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1af70 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  3_realloc() and 
1af80 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1af90 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a  tion is freed..*
1afa0 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65  * ^If sqlite3_re
1afb0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20  alloc() returns 
1afc0 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70  NULL, then the p
1afd0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  rior allocation.
1afe0 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e  ** is not freed.
1aff0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
1b000 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ry returned by s
1b010 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1b020 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  and sqlite3_real
1b030 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61  loc().** is alwa
1b040 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74  ys aligned to at
1b050 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65   least an 8 byte
1b060 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f   boundary, or to
1b070 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75   a.** 4 byte bou
1b080 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51  ndary if the [SQ
1b090 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47  LITE_4_BYTE_ALIG
1b0a0 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70  NED_MALLOC] comp
1b0b0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
1b0c0 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  on is used..**.*
1b0d0 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73  * In SQLite vers
1b0e0 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e  ion 3.5.0 and 3.
1b0f0 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73  5.1, it was poss
1b100 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a  ible to define.*
1b110 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49  * the SQLITE_OMI
1b120 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54  T_MEMORY_ALLOCAT
1b130 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20  ION which would 
1b140 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d  cause the built-
1b150 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  in.** implementa
1b160 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f  tion of these ro
1b170 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69  utines to be omi
1b180 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61  tted.  That capa
1b190 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20  bility.** is no 
1b1a0 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e  longer provided.
1b1b0 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20    Only built-in 
1b1c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
1b1d0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a  s can be used..*
1b1e0 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51  *.** Prior to SQ
1b1f0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
1b200 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73  .10, the Windows
1b210 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
1b220 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68  yer called.** th
1b230 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
1b240 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
1b250 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
1b260 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
1b270 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
1b280 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
1b290 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
1b2a0 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
1b2b0 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
1b2c0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
1b2d0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
1b2e0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
1b2f0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
1b300 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65  tion errors were
1b310 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a   detected, but.*
1b320 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f  * they were repo
1b330 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51  rted back as [SQ
1b340 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f  LITE_CANTOPEN] o
1b350 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  r.** [SQLITE_IOE
1b360 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20  RR] rather than 
1b370 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a  [SQLITE_NOMEM]..
1b380 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65  **.** The pointe
1b390 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b  r arguments to [
1b3a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1b3b0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1b3c0 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20  lloc()].** must 
1b3d0 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f  be either NULL o
1b3e0 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20  r else pointers 
1b3f0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20  obtained from a 
1b400 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74  prior.** invocat
1b410 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ion of [sqlite3_
1b420 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71  malloc()] or [sq
1b430 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1b440 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f   that have.** no
1b450 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61  t yet been relea
1b460 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  sed..**.** The a
1b470 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
1b480 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74  not read or writ
1b490 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a  e any part of.**
1b4a0 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f   a block of memo
1b4b0 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20  ry after it has 
1b4c0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73  been released us
1b4d0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1b4e0 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69  free()] or [sqli
1b4f0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a  te3_realloc()]..
1b500 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1b510 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  id *sqlite3_mall
1b520 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  oc(int);.SQLITE_
1b530 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
1b540 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c  3_realloc(void*,
1b550 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
1b560 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  I void sqlite3_f
1b570 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
1b580 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1b590 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
1b5a0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
1b5b0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
1b5c0 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
1b5d0 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
1b5e0 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
1b5f0 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
1b600 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
1b610 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
1b620 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1b630 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
1b640 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
1b650 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
1b660 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
1b670 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
1b680 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1b690 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
1b6a0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1b6b0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1b6c0 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
1b6d0 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
1b6e0 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
1b6f0 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
1b700 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1b710 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1b720 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1b730 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
1b740 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
1b750 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1b760 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
1b770 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1b780 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
1b790 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
1b7a0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1b7b0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1b7c0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1b7d0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1b7e0 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
1b7f0 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
1b800 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
1b810 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
1b820 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1b830 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
1b840 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
1b850 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
1b860 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
1b870 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
1b880 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
1b890 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
1b8a0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
1b8b0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
1b8c0 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
1b8d0 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
1b8e0 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
1b8f0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1b900 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
1b910 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1b920 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
1b930 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1b940 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
1b950 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1b960 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1b970 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1b980 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
1b990 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1b9a0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
1b9b0 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  set..*/.SQLITE_A
1b9c0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
1b9d0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1b9e0 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49  used(void);.SQLI
1b9f0 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
1ba00 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d  nt64 sqlite3_mem
1ba10 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e  ory_highwater(in
1ba20 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f  t resetFlag);../
1ba30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50  *.** CAPI3REF: P
1ba40 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d  seudo-Random Num
1ba50 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a  ber Generator.**
1ba60 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61  .** SQLite conta
1ba70 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69  ins a high-quali
1ba80 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d  ty pseudo-random
1ba90 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f   number generato
1baa0 72 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f  r (PRNG) used to
1bab0 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f  .** select rando
1bac0 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44  m [ROWID | ROWID
1bad0 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e  s] when insertin
1bae0 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e  g new records in
1baf0 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a  to a table that.
1bb00 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20  ** already uses 
1bb10 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73  the largest poss
1bb20 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54  ible [ROWID].  T
1bb30 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20  he PRNG is also 
1bb40 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20  used for.** the 
1bb50 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28  build-in random(
1bb60 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62  ) and randomblob
1bb70 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  () SQL functions
1bb80 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  .  This interfac
1bb90 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c  e allows.** appl
1bba0 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65  ications to acce
1bbb0 73 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47  ss the same PRNG
1bbc0 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f   for other purpo
1bbd0 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61  ses..**.** ^A ca
1bbe0 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69  ll to this routi
1bbf0 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65  ne stores N byte
1bc00 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
1bc10 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a  into buffer P..*
1bc20 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1bc30 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e  time this routin
1bc40 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69  e is invoked (ei
1bc50 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20  ther internally 
1bc60 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70  or by.** the app
1bc70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52  lication) the PR
1bc80 4e 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69  NG is seeded usi
1bc90 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  ng randomness ob
1bca0 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74  tained.** from t
1bcb0 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d  he xRandomness m
1bcc0 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
1bcd0 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
1bce0 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f  s] object..** ^O
1bcf0 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74  n all subsequent
1bd00 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68   invocations, th
1bd10 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
1bd20 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
1bd30 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
1bd40 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
1bd50 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
1bd60 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
1bd70 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
1bd80 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
1bd90 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f  id sqlite3_rando
1bda0 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69  mness(int N, voi
1bdb0 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d *P);../*.** CA
1bdc0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d  PI3REF: Compile-
1bdd0 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69  Time Authorizati
1bde0 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  on Callbacks.**.
1bdf0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
1be00 20 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75   registers an au
1be10 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1be20 6b 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  k with a particu
1be30 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
1be40 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75   connection], su
1be50 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69  pplied in the fi
1be60 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
1be70 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1be80 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1be90 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74  oked as SQL stat
1bea0 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67  ements are being
1beb0 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20   compiled.** by 
1bec0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1bed0 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61  ()] or its varia
1bee0 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  nts [sqlite3_pre
1bef0 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b  pare_v2()],.** [
1bf00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1bf10 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  6()] and [sqlite
1bf20 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
1bf30 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a  ].  ^At various.
1bf40 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67  ** points during
1bf50 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e   the compilation
1bf60 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67   process, as log
1bf70 69 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61  ic is being crea
1bf80 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72  ted.** to perfor
1bf90 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e  m various action
1bfa0 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  s, the authorize
1bfb0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1bfc0 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20  voked to.** see 
1bfd0 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73  if those actions
1bfe0 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e   are allowed.  ^
1bff0 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1c000 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a  allback should.*
1c010 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
1c020 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68  _OK] to allow th
1c030 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54  e action, [SQLIT
1c040 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73  E_IGNORE] to dis
1c050 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65  allow the.** spe
1c060 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74  cific action but
1c070 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73   allow the SQL s
1c080 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74  tatement to cont
1c090 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f  inue to be.** co
1c0a0 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49  mpiled, or [SQLI
1c0b0 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73  TE_DENY] to caus
1c0c0 65 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  e the entire SQL
1c0d0 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
1c0e0 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74  .** rejected wit
1c0f0 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66  h an error.  ^If
1c100 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1c110 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1c120 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74  .** any value ot
1c130 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
1c140 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54  _IGNORE], [SQLIT
1c150 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  E_OK], or [SQLIT
1c160 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20  E_DENY].** then 
1c170 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
1c180 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1c190 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1c1a0 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20  at triggered.** 
1c1b0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77  the authorizer w
1c1c0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1c1d0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a   error message..
1c1e0 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63  **.** When the c
1c1f0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1c200 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61  [SQLITE_OK], tha
1c210 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72  t means the oper
1c220 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74  ation.** request
1c230 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e  ed is ok.  ^When
1c240 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
1c250 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45  turns [SQLITE_DE
1c260 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  NY], the.** [sql
1c270 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1c280 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1c290 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1c2a0 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68  ered the.** auth
1c2b0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1c2c0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1c2d0 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e  essage explainin
1c2e0 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73  g that.** access
1c2f0 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a   is denied. .**.
1c300 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
1c310 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
1c320 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1c330 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
1c340 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
1c350 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
1c360 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1c370 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65  izer() interface
1c380 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
1c390 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68  rameter.** to th
1c3a0 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e  e callback is an
1c3b0 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45   integer [SQLITE
1c3c0 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63  _COPY | action c
1c3d0 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66  ode] that specif
1c3e0 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69  ies.** the parti
1c3f0 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20  cular action to 
1c400 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e  be authorized. ^
1c410 54 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67  The third throug
1c420 68 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65  h sixth paramete
1c430 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c  rs.** to the cal
1c440 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74  lback are zero-t
1c450 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1c460 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61  s that contain a
1c470 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74  dditional.** det
1c480 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61  ails about the a
1c490 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68  ction to be auth
1c4a0 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  orized..**.** ^I
1c4b0 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64  f the action cod
1c4c0 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41  e is [SQLITE_REA
1c4d0 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61  D].** and the ca
1c4e0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
1c4f0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1c500 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  hen the.** [prep
1c510 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
1c520 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e  statement is con
1c530 73 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73  structed to subs
1c540 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c  titute.** a NULL
1c550 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20   value in place 
1c560 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c  of the table col
1c570 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68  umn that would h
1c580 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64  ave.** been read
1c590 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20   if [SQLITE_OK] 
1c5a0 68 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65  had been returne
1c5b0 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  d.  The [SQLITE_
1c5c0 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72  IGNORE].** retur
1c5d0 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
1c5e0 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74   deny an untrust
1c5f0 65 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74  ed user access t
1c600 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20  o individual.** 
1c610 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62  columns of a tab
1c620 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61  le..** ^If the a
1c630 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53  ction code is [S
1c640 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e  QLITE_DELETE] an
1c650 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1c660 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54  eturns.** [SQLIT
1c670 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74  E_IGNORE] then t
1c680 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72  he [DELETE] oper
1c690 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62  ation proceeds b
1c6a0 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63  ut the.** [trunc
1c6b0 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ate optimization
1c6c0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e  ] is disabled an
1c6d0 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64  d all rows are d
1c6e0 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61  eleted individua
1c6f0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75  lly..**.** An au
1c700 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64  thorizer is used
1c710 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70   when [sqlite3_p
1c720 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69  repare | prepari
1c730 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ng].** SQL state
1c740 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e  ments from an un
1c750 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20  trusted source, 
1c760 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
1c770 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1c780 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20  s.** do not try 
1c790 74 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74  to access data t
1c7a0 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f  hey are not allo
1c7b0 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74  wed to see, or t
1c7c0 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a  hat they do not.
1c7d0 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74  ** try to execut
1c7e0 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74  e malicious stat
1c7f0 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61  ements that dama
1c800 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e  ge the database.
1c810 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65    For.** example
1c820 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
1c830 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65   may allow a use
1c840 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74  r to enter arbit
1c850 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72  rary.** SQL quer
1c860 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69  ies for evaluati
1c870 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65  on by a database
1c880 2e 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69  .  But the appli
1c890 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e  cation does.** n
1c8a0 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72  ot want the user
1c8b0 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d   to be able to m
1c8c0 61 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68  ake arbitrary ch
1c8d0 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20  anges to the.** 
1c8e0 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75  database.  An au
1c8f0 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74  thorizer could t
1c900 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c  hen be put in pl
1c910 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a  ace while the.**
1c920 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51   user-entered SQ
1c930 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69  L is being [sqli
1c940 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
1c950 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20  epared] that.** 
1c960 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74  disallows everyt
1c970 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c  hing except [SEL
1c980 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  ECT] statements.
1c990 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
1c9a0 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f  ons that need to
1c9b0 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f   process SQL fro
1c9c0 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72  m untrusted sour
1c9d0 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73  ces.** might als
1c9e0 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72  o consider lower
1c9f0 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d  ing resource lim
1ca00 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  its using [sqlit
1ca10 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61  e3_limit()].** a
1ca20 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61  nd limiting data
1ca30 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20  base size using 
1ca40 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  the [max_page_co
1ca50 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a  unt] [PRAGMA].**
1ca60 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20   in addition to 
1ca70 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69  using an authori
1ca80 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c  zer..**.** ^(Onl
1ca90 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f  y a single autho
1caa0 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20  rizer can be in 
1cab0 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62  place on a datab
1cac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1cad0 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61  * at a time.  Ea
1cae0 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ch call to sqlit
1caf0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1cb00 72 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a  r overrides the.
1cb10 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  ** previous call
1cb20 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68  .)^  ^Disable th
1cb30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20  e authorizer by 
1cb40 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c  installing a NUL
1cb50 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54  L callback..** T
1cb60 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  he authorizer is
1cb70 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1cb80 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ault..**.** The 
1cb90 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1cba0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
1cbb0 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1cbc0 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1cbd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1cbe0 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1cbf0 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  d the authorizer
1cc00 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f   callback..** No
1cc10 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
1cc20 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
1cc30 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
1cc40 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
1cc50 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
1cc60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
1cc70 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
1cc80 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
1cc90 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
1cca0 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65  ** ^When [sqlite
1ccb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1ccc0 69 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61  is used to prepa
1ccd0 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20  re a statement, 
1cce0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
1ccf0 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65   might be re-pre
1cd00 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71  pared during [sq
1cd10 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75  lite3_step()] du
1cd20 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d  e to a .** schem
1cd30 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65  a change.  Hence
1cd40 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  , the applicatio
1cd50 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20  n should ensure 
1cd60 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72  that the.** corr
1cd70 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63  ect authorizer c
1cd80 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20  allback remains 
1cd90 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20  in place during 
1cda0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
1cdb0 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74  p()]..**.** ^Not
1cdc0 65 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f  e that the autho
1cdd0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1cde0 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64  s invoked only d
1cdf0 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  uring.** [sqlite
1ce00 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20  3_prepare()] or 
1ce10 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41  its variants.  A
1ce20 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20  uthorization is 
1ce30 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64  not.** performed
1ce40 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e   during statemen
1ce50 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20  t evaluation in 
1ce60 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1ce70 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73  , unless.** as s
1ce80 74 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65  tated in the pre
1ce90 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c  vious paragraph,
1cea0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
1ceb0 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74  invokes.** sqlit
1cec0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
1ced0 74 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73  to reprepare a s
1cee0 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61  tatement after a
1cef0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a   schema change..
1cf00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1cf10 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  t sqlite3_set_au
1cf20 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69  thorizer(.  sqli
1cf30 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41  te3*,.  int (*xA
1cf40 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  uth)(void*,int,c
1cf50 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1cf60 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
1cf70 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c  r*,const char*),
1cf80 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61  .  void *pUserDa
1cf90 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ta.);../*.** CAP
1cfa0 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65  I3REF: Authorize
1cfb0 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a  r Return Codes.*
1cfc0 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  *.** The [sqlite
1cfd0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1cfe0 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61   | authorizer ca
1cff0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d  llback function]
1d000 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20   must.** return 
1d010 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f  either [SQLITE_O
1d020 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65  K] or one of the
1d030 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73  se two constants
1d040 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20   in order.** to 
1d050 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68  signal SQLite wh
1d060 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
1d070 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69   action is permi
1d080 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a  tted.  See the.*
1d090 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  * [sqlite3_set_a
1d0a0 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68  uthorizer | auth
1d0b0 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61  orizer documenta
1d0c0 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69  tion] for additi
1d0d0 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
1d0e0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ion..**.** Note 
1d0f0 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f  that SQLITE_IGNO
1d100 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20  RE is also used 
1d110 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c  as a [SQLITE_ROL
1d120 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63  LBACK | return c
1d130 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ode].** from the
1d140 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f   [sqlite3_vtab_o
1d150 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e  n_conflict()] in
1d160 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66  terface..*/.#def
1d170 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20  ine SQLITE_DENY 
1d180 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74    1   /* Abort t
1d190 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1d1a0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a   with an error *
1d1b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d1c0 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44  _IGNORE 2   /* D
1d1d0 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73  on't allow acces
1d1e0 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e  s, but don't gen
1d1f0 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a  erate an error *
1d200 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1d210 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63  F: Authorizer Ac
1d220 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  tion Codes.**.**
1d230 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
1d240 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20  t_authorizer()] 
1d250 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74  interface regist
1d260 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ers a callback f
1d270 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  unction.** that 
1d280 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75  is invoked to au
1d290 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20  thorize certain 
1d2a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63  SQL statement ac
1d2b0 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73  tions.  The.** s
1d2c0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1d2d0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1d2e0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  is an integer co
1d2f0 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65  de that specifie
1d300 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e  s.** what action
1d310 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72   is being author
1d320 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65  ized.  These are
1d330 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74   the integer act
1d340 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a  ion codes that.*
1d350 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1d360 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65   callback may be
1d370 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   passed..**.** T
1d380 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65  hese action code
1d390 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20   values signify 
1d3a0 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65  what kind of ope
1d3b0 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a  ration is to be.
1d3c0 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20  ** authorized.  
1d3d0 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20  The 3rd and 4th 
1d3e0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
1d3f0 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a  e authorization.
1d400 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  ** callback func
1d410 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72  tion will be par
1d420 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20  ameters or NULL 
1d430 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69  depending on whi
1d440 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63  ch of these.** c
1d450 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20  odes is used as 
1d460 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1d470 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68  eter.  ^(The 5th
1d480 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1d490 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20  e.** authorizer 
1d4a0 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1d4b0 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
1d4c0 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74  base ("main", "t
1d4d0 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69  emp",.** etc.) i
1d4e0 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20  f applicable.)^ 
1d4f0 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65   ^The 6th parame
1d500 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1d510 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a  rizer callback.*
1d520 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  * is the name of
1d530 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20   the inner-most 
1d540 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20  trigger or view 
1d550 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69  that is responsi
1d560 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ble for.** the a
1d570 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72  ccess attempt or
1d580 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63   NULL if this ac
1d590 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20  cess attempt is 
1d5a0 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a  directly from.**
1d5b0 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63   top-level SQL c
1d5c0 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ode..*/./*******
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 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a  **** 3rd *******
1d600 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a  ***** 4th ******
1d610 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  *****/.#define S
1d620 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44  QLITE_CREATE_IND
1d630 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20  EX          1   
1d640 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1d650 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1d660 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1d670 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c  LITE_CREATE_TABL
1d680 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f  E          2   /
1d690 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1d6a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1d6b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1d6c0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1d6d0 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a  INDEX     3   /*
1d6e0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1d6f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1d700 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1d710 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1d720 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20  ABLE     4   /* 
1d730 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1d740 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1d750 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1d760 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52  E_CREATE_TEMP_TR
1d770 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54  IGGER   5   /* T
1d780 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
1d790 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1d7a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1d7b0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45  _CREATE_TEMP_VIE
1d7c0 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69  W      6   /* Vi
1d7d0 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
1d7e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1d7f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1d800 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20  CREATE_TRIGGER  
1d810 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69        7   /* Tri
1d820 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1d830 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1d840 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1d850 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20  REATE_VIEW      
1d860 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77       8   /* View
1d870 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1d880 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1d890 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1d8a0 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
1d8b0 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65      9   /* Table
1d8c0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
1d8d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1d8e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1d8f0 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  P_INDEX         
1d900 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20    10   /* Index 
1d910 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1d920 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1d930 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1d940 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1d950 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   11   /* Table N
1d960 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1d970 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1d980 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1d990 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20  TEMP_INDEX      
1d9a0 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  12   /* Index Na
1d9b0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1d9c0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1d9d0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1d9e0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31  EMP_TABLE      1
1d9f0 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1da00 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1da10 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1da20 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1da30 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34  MP_TRIGGER    14
1da40 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1da50 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1da60 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1da70 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1da80 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20  P_VIEW       15 
1da90 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1daa0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1dab0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1dac0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47  SQLITE_DROP_TRIG
1dad0 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20  GER         16  
1dae0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1daf0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1db00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1db10 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20  QLITE_DROP_VIEW 
1db20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20             17   
1db30 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1db40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1db50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1db60 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20  LITE_INSERT     
1db70 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f            18   /
1db80 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1db90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1dba0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1dbb0 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20  ITE_PRAGMA      
1dbc0 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a           19   /*
1dbd0 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20   Pragma Name    
1dbe0 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c   1st arg or NULL
1dbf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1dc00 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20  TE_READ         
1dc10 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20          20   /* 
1dc20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1dc30 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20  Column Name     
1dc40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1dc50 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20  E_SELECT        
1dc60 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e         21   /* N
1dc70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e  ULL            N
1dc80 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1dc90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1dca0 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20  _TRANSACTION    
1dcb0 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70        22   /* Op
1dcc0 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55  eration       NU
1dcd0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1dce0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1dcf0 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20  UPDATE          
1dd00 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62       23   /* Tab
1dd10 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1dd20 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1dd30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
1dd40 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  TTACH           
1dd50 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65      24   /* File
1dd60 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c  name        NULL
1dd70 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1dd80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
1dd90 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
1dda0 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62     25   /* Datab
1ddb0 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20  ase Name   NULL 
1ddc0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1ddd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54  efine SQLITE_ALT
1dde0 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  ER_TABLE        
1ddf0 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61    26   /* Databa
1de00 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20  se Name   Table 
1de10 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1de20 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e  fine SQLITE_REIN
1de30 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20  DEX             
1de40 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   27   /* Index N
1de50 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1de60 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1de70 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59  ine SQLITE_ANALY
1de80 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ZE              
1de90 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  28   /* Table Na
1dea0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1deb0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1dec0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ded0 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32  _VTABLE        2
1dee0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
1def0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1df00 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1df10 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54  e SQLITE_DROP_VT
1df20 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30  ABLE          30
1df30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1df40 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
1df50 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
1df60 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e   SQLITE_FUNCTION
1df70 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20               31 
1df80 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
1df90 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61       Function Na
1dfa0 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  me   */.#define 
1dfb0 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54  SQLITE_SAVEPOINT
1dfc0 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20              32  
1dfd0 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
1dfe0 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61      Savepoint Na
1dff0 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  me  */.#define S
1e000 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20  QLITE_COPY      
1e010 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20              0   
1e020 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65  /* No longer use
1e030 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
1e040 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e  3REF: Tracing An
1e050 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63  d Profiling Func
1e060 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
1e070 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73  e routines regis
1e080 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  ter callback fun
1e090 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20  ctions that can 
1e0a0 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  be used for.** t
1e0b0 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69  racing and profi
1e0c0 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69  ling the executi
1e0d0 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d  on of SQL statem
1e0e0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ents..**.** ^The
1e0f0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1e100 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79  on registered by
1e110 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1e120 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a   is invoked at.*
1e130 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20  * various times 
1e140 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  when an SQL stat
1e150 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72  ement is being r
1e160 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  un by [sqlite3_s
1e170 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20  tep()]..** ^The 
1e180 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
1e190 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1e1a0 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38  ked with a UTF-8
1e1b0 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68   rendering of th
1e1c0 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  e.** SQL stateme
1e1d0 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73  nt text as the s
1e1e0 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62  tatement first b
1e1f0 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e  egins executing.
1e200 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c  .** ^(Additional
1e210 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1e220 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74   callbacks might
1e230 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63   occur.** as eac
1e240 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70  h triggered subp
1e250 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65  rogram is entere
1e260 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  d.  The callback
1e270 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a  s for triggers.*
1e280 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d  * contain a UTF-
1e290 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68  8 SQL comment th
1e2a0 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68  at identifies th
1e2b0 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a  e trigger.)^.**.
1e2c0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1e2d0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1e2e0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1e2f0 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
1e300 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
1e310 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
1e320 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
1e330 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
1e340 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
1e350 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1e360 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
1e370 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
1e380 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
1e390 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
1e3a0 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
1e3b0 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
1e3c0 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
1e3d0 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
1e3e0 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
1e3f0 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
1e400 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
1e410 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
1e420 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
1e430 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
1e440 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
1e450 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
1e460 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
1e470 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
1e480 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
1e490 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
1e4a0 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
1e4b0 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
1e4c0 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
1e4d0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
1e4e0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
1e4f0 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
1e500 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
1e510 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
1e520 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
1e530 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
1e540 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1e550 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ite..*/.SQLITE_A
1e560 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
1e570 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c  _trace(sqlite3*,
1e580 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76   void(*xTrace)(v
1e590 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
1e5a0 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54  ), void*);.SQLIT
1e5b0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50  E_API SQLITE_EXP
1e5c0 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a  ERIMENTAL void *
1e5d0 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28  sqlite3_profile(
1e5e0 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69  sqlite3*,.   voi
1e5f0 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69  d(*xProfile)(voi
1e600 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73  d*,const char*,s
1e610 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20  qlite3_uint64), 
1e620 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1e630 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50  API3REF: Query P
1e640 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b  rogress Callback
1e650 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
1e660 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61  ite3_progress_ha
1e670 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69  ndler(D,N,X,P) i
1e680 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
1e690 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  the callback.** 
1e6a0 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65  function X to be
1e6b0 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69   invoked periodi
1e6c0 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e  cally during lon
1e6d0 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20  g running calls 
1e6e0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  to.** [sqlite3_e
1e6f0 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  xec()], [sqlite3
1e700 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71  _step()] and [sq
1e710 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1e720 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61  )] for.** databa
1e730 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  se connection D.
1e740 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65    An example use
1e750 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74   for this.** int
1e760 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65  erface is to kee
1e770 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20  p a GUI updated 
1e780 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71  during a large q
1e790 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  uery..**.** ^The
1e7a0 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
1e7b0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
1e7c0 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d  s the only param
1e7d0 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20  eter to the .** 
1e7e0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1e7f0 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d  n X.  ^The param
1e800 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75  eter N is the nu
1e810 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
1e820 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
1e830 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
1e840 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
1e850 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
1e860 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
1e870 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
1e880 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61  X..**.** ^Only a
1e890 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73   single progress
1e8a0 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20   handler may be 
1e8b0 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74  defined at one t
1e8c0 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61  ime per.** [data
1e8d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1e8e0 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20  ; setting a new 
1e8f0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1e900 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20   cancels the.** 
1e910 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69  old one.  ^Setti
1e920 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74  ng parameter X t
1e930 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20  o NULL disables 
1e940 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  the progress han
1e950 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72  dler..** ^The pr
1e960 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69  ogress handler i
1e970 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20  s also disabled 
1e980 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20  by setting N to 
1e990 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20  a value less.** 
1e9a0 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49  than 1..**.** ^I
1e9b0 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63  f the progress c
1e9c0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1e9d0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70  non-zero, the op
1e9e0 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e  eration is.** in
1e9f0 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73  terrupted.  This
1ea00 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20   feature can be 
1ea10 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1ea20 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20  t a.** "Cancel" 
1ea30 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20  button on a GUI 
1ea40 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20  progress dialog 
1ea50 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  box..**.** The p
1ea60 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1ea70 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
1ea80 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
1ea90 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
1eaa0 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1eab0 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1eac0 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72  nvoked the progr
1ead0 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1eae0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1eaf0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1eb00 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1eb10 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1eb20 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1eb30 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1eb40 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1eb50 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1eb60 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1eb70 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  *.*/.SQLITE_API 
1eb80 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
1eb90 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
1eba0 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
1ebb0 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
1ebc0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1ebd0 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
1ebe0 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
1ebf0 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
1ec00 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
1ec10 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
1ec20 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
1ec30 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
1ec40 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
1ec50 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
1ec60 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
1ec70 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
1ec80 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
1ec90 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1eca0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1ecb0 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
1ecc0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1ecd0 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
1ece0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
1ecf0 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
1ed00 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
1ed10 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
1ed20 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
1ed30 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
1ed40 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
1ed50 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
1ed60 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
1ed70 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
1ed80 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1ed90 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
1eda0 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
1edb0 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
1edc0 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
1edd0 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
1ede0 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1edf0 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
1ee00 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
1ee10 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1ee20 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
1ee30 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
1ee40 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
1ee50 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
1ee60 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
1ee70 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
1ee80 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
1ee90 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
1eea0 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
1eeb0 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
1eec0 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
1eed0 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
1eee0 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
1eef0 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
1ef00 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
1ef10 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
1ef20 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
1ef30 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
1ef40 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
1ef50 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1ef60 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
1ef70 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1ef80 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
1ef90 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1efa0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1efb0 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
1efc0 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
1efd0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1efe0 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
1eff0 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
1f000 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
1f010 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
1f020 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
1f030 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
1f040 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
1f050 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
1f060 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1f070 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
1f080 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
1f090 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
1f0a0 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
1f0b0 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
1f0c0 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
1f0d0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1f0e0 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
1f0f0 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
1f100 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
1f110 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1f120 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
1f130 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
1f140 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
1f150 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
1f160 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1f170 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1f180 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
1f190 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
1f1a0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
1f1b0 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
1f1c0 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
1f1d0 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
1f1e0 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
1f1f0 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
1f200 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1f210 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1f220 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
1f230 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1f240 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  CACHE],.** [SQLI
1f250 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1f260 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53  ACHE], and/or [S
1f270 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20  QLITE_OPEN_URI] 
1f280 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c  flags:)^.**.** <
1f290 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  dl>.** ^(<dt>[SQ
1f2a0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1f2b0 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LY]</dt>.** <dd>
1f2c0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1f2d0 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f  opened in read-o
1f2e0 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  nly mode.  If th
1f2f0 65 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20  e database does 
1f300 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65  not.** already e
1f310 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69  xist, an error i
1f320 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e  s returned.</dd>
1f330 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b  )^.**.** ^(<dt>[
1f340 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
1f350 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c  WRITE]</dt>.** <
1f360 64 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20  dd>The database 
1f370 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
1f380 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e  ading and writin
1f390 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f  g if possible, o
1f3a0 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c  r reading.** onl
1f3b0 79 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73  y if the file is
1f3c0 20 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64   write protected
1f3d0 20 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e   by the operatin
1f3e0 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69  g system.  In ei
1f3f0 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65  ther.** case the
1f400 20 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61   database must a
1f410 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74  lready exist, ot
1f420 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
1f430 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
1f440 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1f450 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
1f460 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
1f470 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c  TE_OPEN_CREATE]<
1f480 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1f490 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1f4a0 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  ed for reading a
1f4b0 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20  nd writing, and 
1f4c0 69 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a  is created if.**
1f4d0 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72   it does not alr
1f4e0 65 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73  eady exist. This
1f4f0 20 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72   is the behavior
1f500 20 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20   that is always 
1f510 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69  used for.** sqli
1f520 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1f530 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e  qlite3_open16().
1f540 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
1f550 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72  .**.** If the 3r
1f560 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1f570 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1f580 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74   is not one of t
1f590 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f  he.** combinatio
1f5a0 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f  ns shown above o
1f5b0 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e  ptionally combin
1f5c0 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a  ed with other.**
1f5d0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
1f5e0 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f  ADONLY | SQLITE_
1f5f0 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20  OPEN_* bits].** 
1f600 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
1f610 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
1f620 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53  **.** ^If the [S
1f630 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54  QLITE_OPEN_NOMUT
1f640 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c  EX] flag is set,
1f650 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1f660 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1f670 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75   opens in the mu
1f680 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65  lti-thread [thre
1f690 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c  ading mode] as l
1f6a0 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c  ong as the singl
1f6b0 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65  e-thread.** mode
1f6c0 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65   has not been se
1f6d0 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  t at compile-tim
1f6e0 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e  e or start-time.
1f6f0 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51    ^If the.** [SQ
1f700 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
1f710 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1f720 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
1f730 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70  se connection op
1f740 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65  ens.** in the se
1f750 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
1f760 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73  ing mode] unless
1f770 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77   single-thread w
1f780 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  as.** previously
1f790 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d   selected at com
1f7a0 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61  pile-time or sta
1f7b0 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65  rt-time..** ^The
1f7c0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48   [SQLITE_OPEN_SH
1f7d0 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20  AREDCACHE] flag 
1f7e0 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62  causes the datab
1f7f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1f800 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65  o be.** eligible
1f810 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20   to use [shared 
1f820 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67  cache mode], reg
1f830 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1f840 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
1f850 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61  .** cache is ena
1f860 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  bled using [sqli
1f870 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
1f880 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68  d_cache()].  ^Th
1f890 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  e.** [SQLITE_OPE
1f8a0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20  N_PRIVATECACHE] 
1f8b0 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
1f8c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f8d0 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61  ion to not.** pa
1f8e0 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68  rticipate in [sh
1f8f0 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
1f900 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65   even if it is e
1f910 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  nabled..**.** ^T
1f920 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
1f930 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
1f940 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20  pen_v2() is the 
1f950 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  name of the.** [
1f960 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
1f970 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73  ect that defines
1f980 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1f990 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20  ystem interface 
1f9a0 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20  that.** the new 
1f9b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1f9c0 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20  ion should use. 
1f9d0 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
1f9e0 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20  parameter is.** 
1f9f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1fa00 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20  hen the default 
1fa10 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1fa20 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a  ject is used..**
1fa30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65  .** ^If the file
1fa40 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79  name is ":memory
1fa50 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61  :", then a priva
1fa60 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e  te, temporary in
1fa70 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
1fa80 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66  .** is created f
1fa90 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  or the connectio
1faa0 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d  n.  ^This in-mem
1fab0 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c  ory database wil
1fac0 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a  l vanish when.**
1fad0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1fae0 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
1faf0 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ed.  Future vers
1fb00 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1fb10 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65  ight.** make use
1fb20 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73   of additional s
1fb30 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73  pecial filenames
1fb40 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68   that begin with
1fb50 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74   the ":" charact
1fb60 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63  er..** It is rec
1fb70 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68  ommended that wh
1fb80 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  en a database fi
1fb90 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20  lename actually 
1fba0 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a  does begin with.
1fbb0 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74  ** a ":" charact
1fbc0 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72  er you should pr
1fbd0 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d  efix the filenam
1fbe0 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d  e with a pathnam
1fbf0 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f  e such as.** "./
1fc00 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67  " to avoid ambig
1fc10 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  uity..**.** ^If 
1fc20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
1fc30 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c  an empty string,
1fc40 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
1fc50 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e   temporary.** on
1fc60 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77  -disk database w
1fc70 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20  ill be created. 
1fc80 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64   ^This private d
1fc90 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a  atabase will be.
1fca0 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ** automatically
1fcb0 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e   deleted as soon
1fcc0 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65   as the database
1fcd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63   connection is c
1fce0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  losed..**.** [[U
1fcf0 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20  RI filenames in 
1fd00 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d  sqlite3_open()]]
1fd10 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d   <h3>URI Filenam
1fd20 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49  es</h3>.**.** ^I
1fd30 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d  f [URI filename]
1fd40 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20   interpretation 
1fd50 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20  is enabled, and 
1fd60 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1fd70 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20  ument.** begins 
1fd80 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68  with "file:", th
1fd90 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  en the filename 
1fda0 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
1fdb0 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a  s a URI. ^URI.**
1fdc0 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70   filename interp
1fdd0 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62  retation is enab
1fde0 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49  led if the [SQLI
1fdf0 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
1fe00 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74  g is.** set in t
1fe10 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
1fe20 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  nt to sqlite3_op
1fe30 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69  en_v2(), or if i
1fe40 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e  t has.** been en
1fe50 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75  abled globally u
1fe60 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45  sing the [SQLITE
1fe70 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74  _CONFIG_URI] opt
1fe80 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ion with the.** 
1fe90 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
1fea0 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20  )] method or by 
1feb0 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  the [SQLITE_USE_
1fec0 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  URI] compile-tim
1fed0 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20  e option..** As 
1fee0 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  of SQLite versio
1fef0 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c  n 3.7.7, URI fil
1ff00 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
1ff10 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f  tion is turned o
1ff20 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74  ff.** by default
1ff30 2c 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c  , but future rel
1ff40 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20  eases of SQLite 
1ff50 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49  might enable URI
1ff60 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74   filename.** int
1ff70 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64  erpretation by d
1ff80 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55  efault.  See "[U
1ff90 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66  RI filenames]" f
1ffa0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  or additional.**
1ffb0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
1ffc0 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
1ffd0 73 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63  s are parsed acc
1ffe0 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39  ording to RFC 39
1fff0 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20  86. ^If the URI 
20000 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61  contains an.** a
20010 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69  uthority, then i
20020 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
20030 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
20040 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
20050 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
20060 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
20070 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
20080 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
20090 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
200a0 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
200b0 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
200c0 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63   ^The fragment c
200d0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
200e0 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e  I, if .** presen
200f0 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  t, is ignored..*
20100 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  *.** ^SQLite use
20110 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f  s the path compo
20120 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20  nent of the URI 
20130 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  as the name of t
20140 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20  he disk file.** 
20150 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74  which contains t
20160 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66  he database. ^If
20170 20 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73   the path begins
20180 20 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72   with a '/' char
20190 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20  acter, .** then 
201a0 69 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  it is interprete
201b0 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65  d as an absolute
201c0 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70   path. ^If the p
201d0 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67  ath does not beg
201e0 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f  in .** with a '/
201f0 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20  ' (meaning that 
20200 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65  the authority se
20210 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64  ction is omitted
20220 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a   from the URI).*
20230 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20  * then the path 
20240 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
20250 73 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74  s a relative pat
20260 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f  h. .** ^On windo
20270 77 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f  ws, the first co
20280 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62  mponent of an ab
20290 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20  solute path .** 
202a0 69 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69  is a drive speci
202b0 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22  fication (e.g. "
202c0 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f  C:")..**.** [[co
202d0 72 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72  re URI query par
202e0 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65  ameters]].** The
202f0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
20300 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f   of a URI may co
20310 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73  ntain parameters
20320 20 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70   that are interp
20330 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20  reted.** either 
20340 62 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66  by SQLite itself
20350 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c  , or by a [VFS |
20360 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c   custom VFS impl
20370 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20  ementation]..** 
20380 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
20390 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  s the following 
203a0 74 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61  three query para
203b0 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  meters:.**.** <u
203c0 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e  l>.**   <li> <b>
203d0 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76  vfs</b>: ^The "v
203e0 66 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61  fs" parameter ma
203f0 79 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65  y be used to spe
20400 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66  cify the name of
20410 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62  .**     a VFS ob
20420 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64  ject that provid
20430 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
20440 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
20450 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a  e that should.**
20460 20 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20       be used to 
20470 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
20480 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b  ase file on disk
20490 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f  . ^If this optio
204a0 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20  n is set to.**  
204b0 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69     an empty stri
204c0 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56  ng the default V
204d0 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  FS object is use
204e0 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61  d. ^Specifying a
204f0 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20  n unknown.**    
20500 20 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72   VFS is an error
20510 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70  . ^If sqlite3_op
20520 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20  en_v2() is used 
20530 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69  and the vfs opti
20540 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65  on is.**     pre
20550 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56  sent, then the V
20560 46 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20  FS specified by 
20570 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  the option takes
20580 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72   precedence over
20590 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75  .**     the valu
205a0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
205b0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
205c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
205d0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
205e0 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a  li> <b>mode</b>:
205f0 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61   ^(The mode para
20600 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74  meter may be set
20610 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c   to either "ro",
20620 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72   "rw",.**     "r
20630 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22  wc", or "memory"
20640 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  . Attempting to 
20650 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74  set it to any ot
20660 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20  her value is.** 
20670 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20      an error)^. 
20680 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22  .**     ^If "ro"
20690 20 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74   is specified, t
206a0 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
206b0 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
206c0 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20  ead-only .**    
206d0 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73   access, just as
206e0 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
206f0 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66  OPEN_READONLY] f
20700 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74  lag had been set
20710 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20   in the .**     
20720 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74  third argument t
20730 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
20740 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64  2(). ^If the mod
20750 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20  e option is set 
20760 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c  to .**     "rw",
20770 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
20780 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
20790 20 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74   read-write (but
207a0 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a   not create) .**
207b0 20 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20       access, as 
207c0 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  if SQLITE_OPEN_R
207d0 45 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f  EADWRITE (but no
207e0 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  t SQLITE_OPEN_CR
207f0 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20  EATE) had .**   
20800 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c    been set. ^Val
20810 75 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69  ue "rwc" is equi
20820 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
20830 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53  g both .**     S
20840 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
20850 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  RITE and SQLITE_
20860 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49  OPEN_CREATE.  ^I
20870 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
20880 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20  n is.**     set 
20890 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e  to "memory" then
208a0 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f   a pure [in-memo
208b0 72 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61  ry database] tha
208c0 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a  t never reads.**
208d0 20 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66       or writes f
208e0 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64  rom disk is used
208f0 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f  . ^It is an erro
20900 72 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76  r to specify a v
20910 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20  alue for.**     
20920 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  the mode paramet
20930 65 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20  er that is less 
20940 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
20950 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
20960 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c  by.**     the fl
20970 61 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68  ags passed in th
20980 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
20990 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
209a0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  n_v2()..**.**   
209b0 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62  <li> <b>cache</b
209c0 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61  >: ^The cache pa
209d0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
209e0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68  et to either "sh
209f0 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20  ared" or.**     
20a00 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74  "private". ^Sett
20a10 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65  ing it to "share
20a20 64 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  d" is equivalent
20a30 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a   to setting the.
20a40 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
20a50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62  EN_SHAREDCACHE b
20a60 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20  it in the flags 
20a70 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
20a80 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65  to.**     sqlite
20a90 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65  3_open_v2(). ^Se
20aa0 74 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20  tting the cache 
20ab0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72  parameter to "pr
20ac0 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20  ivate" is .**   
20ad0 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20    equivalent to 
20ae0 73 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49  setting the SQLI
20af0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
20b00 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20  ACHE bit..**    
20b10 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
20b20 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
20b30 6e 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70  nd the "cache" p
20b40 61 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73  arameter is pres
20b50 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20  ent in.**     a 
20b60 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74  URI filename, it
20b70 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65  s value override
20b80 73 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20  s any behaviour 
20b90 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74  requested by set
20ba0 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49  ting.**     SQLI
20bb0 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
20bc0 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f  ACHE or SQLITE_O
20bd0 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
20be0 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  flag..** </ul>.*
20bf0 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67  *.** ^Specifying
20c00 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61   an unknown para
20c10 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65  meter in the que
20c20 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
20c30 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a  a URI is not an.
20c40 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72  ** error.  Futur
20c50 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
20c60 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72  Lite might under
20c70 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c  stand additional
20c80 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
20c90 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65  ters.  See "[que
20ca0 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69  ry parameters wi
20cb0 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69  th special meani
20cc0 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66  ng to SQLite]" f
20cd0 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c  or.** additional
20ce0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a   information..**
20cf0 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61  .** [[URI filena
20d00 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68  me examples]] <h
20d10 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65  3>URI filename e
20d20 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  xamples</h3>.**.
20d30 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
20d40 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65  ="1" align=cente
20d50 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e  r cellpadding=5>
20d60 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49  .** <tr><th> URI
20d70 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20   filenames <th> 
20d80 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c  Results.** <tr><
20d90 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62  td> file:data.db
20da0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
20db0 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65     Open the file
20dc0 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
20dd0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
20de0 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ory..** <tr><td>
20df0 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
20e00 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20  /data.db<br>.** 
20e10 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
20e20 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
20e30 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20  db <br> .**     
20e40 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61       file://loca
20e50 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f  lhost/home/fred/
20e60 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64  data.db <br> <td
20e70 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
20e80 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
20e90 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
20ea0 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c  d/data.db"..** <
20eb0 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64  tr><td> file://d
20ec0 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65  arkstar/home/fre
20ed0 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  d/data.db <td> .
20ee0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
20ef0 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22  rror. "darkstar"
20f00 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e   is not a recogn
20f10 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a  ized authority..
20f20 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65  ** <tr><td style
20f30 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f  ="white-space:no
20f40 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20  wrap"> .**      
20f50 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44      file:///C:/D
20f60 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32  ocuments%20and%2
20f70 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44  0Settings/fred/D
20f80 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a  esktop/data.db.*
20f90 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f  *     <td> Windo
20fa0 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68  ws only: Open th
20fb0 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
20fc0 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74   on fred's deskt
20fd0 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20  op on drive.**  
20fe0 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65          C:. Note
20ff0 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73   that the %20 es
21000 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65  caping in this e
21010 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74  xample is not st
21020 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20  rictly .**      
21030 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20      necessary - 
21040 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73  space characters
21050 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74   can be used lit
21060 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20  erally.**       
21070 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61     in URI filena
21080 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  mes..** <tr><td>
21090 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
210a0 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76  de=ro&cache=priv
210b0 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  ate <td> .**    
210c0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
210d0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
210e0 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
210f0 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79  ry for read-only
21100 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20   access..**     
21110 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20       Regardless 
21120 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
21130 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d  t shared-cache m
21140 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62  ode is enabled b
21150 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65  y.**          de
21160 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69  fault, use a pri
21170 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c  vate cache..** <
21180 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f  tr><td> file:/ho
21190 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f  me/fred/data.db?
211a0 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20  vfs=unix-nolock 
211b0 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <td>.**         
211c0 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d   Open file "/hom
211d0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
211e0 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c   Use the special
211f0 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63   VFS "unix-noloc
21200 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  k"..** <tr><td> 
21210 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
21220 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20  e=readonly <td> 
21230 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
21240 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79  error. "readonly
21250 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64  " is not a valid
21260 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20   option for the 
21270 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72  "mode" parameter
21280 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  ..** </table>.**
21290 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63  .** ^URI hexadec
212a0 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
212b0 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20  ences (%HH) are 
212c0 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e  supported within
212d0 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a   the path and.**
212e0 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74   query component
212f0 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65  s of a URI. A he
21300 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
21310 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73   sequence consis
21320 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65  ts of a.** perce
21330 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20  nt sign - "%" - 
21340 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63  followed by exac
21350 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69  tly two hexadeci
21360 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73  mal digits .** s
21370 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74  pecifying an oct
21380 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72  et value. ^Befor
21390 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75  e the path or qu
213a0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
213b0 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e  f a.** URI filen
213c0 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65  ame are interpre
213d0 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e  ted, they are en
213e0 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d  coded using UTF-
213f0 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65  8 and all .** he
21400 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
21410 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61   sequences repla
21420 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20  ced by a single 
21430 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  byte containing 
21440 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e  the.** correspon
21450 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74  ding octet. If t
21460 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65  his process gene
21470 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64  rates an invalid
21480 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c   UTF-8 encoding,
21490 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20  .** the results 
214a0 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
214b0 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20  *.** <b>Note to 
214c0 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f  Windows users:</
214d0 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67  b>  The encoding
214e0 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69   used for the fi
214f0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
21500 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70  ** of sqlite3_op
21510 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
21520 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20  _open_v2() must 
21530 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68  be UTF-8, not wh
21540 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61  atever.** codepa
21550 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  ge is currently 
21560 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61  defined.  Filena
21570 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69  mes containing i
21580 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20  nternational.** 
21590 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20  characters must 
215a0 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20  be converted to 
215b0 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70  UTF-8 prior to p
215c0 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f  assing them into
215d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
215e0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
215f0 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c  en_v2()..**.** <
21600 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
21610 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a  s Runtime users:
21620 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72  </b>  The tempor
21630 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75  ary directory mu
21640 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69  st be set.** pri
21650 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71  or to calling sq
21660 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
21670 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
21680 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76  ).  Otherwise, v
21690 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72  arious.** featur
216a0 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20  es that require 
216b0 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f  the use of tempo
216c0 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66  rary files may f
216d0 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ail..**.** See a
216e0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65  lso: [sqlite3_te
216f0 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f  mp_directory].*/
21700 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
21710 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20  sqlite3_open(.  
21720 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
21730 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
21740 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
21750 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
21760 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20  3 **ppDb        
21770 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
21780 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b   db handle */.);
21790 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
217a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a  sqlite3_open16(.
217b0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69    const void *fi
217c0 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
217d0 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
217e0 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c  UTF-16) */.  sql
217f0 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20  ite3 **ppDb     
21800 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c       /* OUT: SQL
21810 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f  ite db handle */
21820 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
21830 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
21840 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
21850 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
21860 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
21870 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
21880 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
21890 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
218a0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
218b0 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
218c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
218d0 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
218e0 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
218f0 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
21900 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
21910 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
21920 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56  PI3REF: Obtain V
21930 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61  alues For URI Pa
21940 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54  rameters.**.** T
21950 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79  hese are utility
21960 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75   routines, usefu
21970 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65  l to VFS impleme
21980 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63  ntations, that c
21990 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69  heck.** to see i
219a0 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  f a database fil
219b0 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74  e was a URI that
219c0 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65   contained a spe
219d0 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20  cific query .** 
219e0 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69  parameter, and i
219f0 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65  f so obtains the
21a00 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71   value of that q
21a10 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a  uery parameter..
21a20 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68  **.** If F is th
21a30 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  e database filen
21a40 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73  ame pointer pass
21a50 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
21a60 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a  n() method of .*
21a70 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  * a VFS implemen
21a80 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20  tation when the 
21a90 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20  flags parameter 
21aa0 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f  to xOpen() has o
21ab0 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f  ne or .** more o
21ac0 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  f the [SQLITE_OP
21ad0 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49  EN_URI] or [SQLI
21ae0 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
21af0 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a   bits set and.**
21b00 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f   P is the name o
21b10 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61  f the query para
21b20 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73  meter, then.** s
21b30 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
21b40 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
21b50 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
21b60 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65  he P.** paramete
21b70 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f  r if it exists o
21b80 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
21b90 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61   if P does not a
21ba0 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71  ppear as a .** q
21bb0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
21bc0 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20  n F.  If P is a 
21bd0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
21be0 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65  of F.** has no e
21bf0 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74  xplicit value, t
21c00 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
21c10 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
21c20 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e  eturns.** a poin
21c30 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20  ter to an empty 
21c40 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
21c50 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  e sqlite3_uri_bo
21c60 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
21c70 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61  tine assumes tha
21c80 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e  t P is a boolean
21c90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e  .** parameter an
21ca0 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  d returns true (
21cb0 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20  1) or false (0) 
21cc0 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65  according to the
21cd0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20   value.** of P. 
21ce0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
21cf0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
21d00 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
21d10 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a  true (1) if the.
21d20 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72  ** value of quer
21d30 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  y parameter P is
21d40 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22   one of "yes", "
21d50 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69  true", or "on" i
21d60 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72  n any.** case or
21d70 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
21d80 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d  gins with a non-
21d90 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68  zero number.  Th
21da0 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72  e .** sqlite3_ur
21db0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
21dc0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
21dd0 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74  s false (0) if t
21de0 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71  he value of.** q
21df0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50  uery parameter P
21e00 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c   is one of "no",
21e10 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66   "false", or "of
21e20 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f  f" in any case o
21e30 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75  r.** if the valu
21e40 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
21e50 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49  numeric zero.  I
21e60 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65  f P is not a que
21e70 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ry.** parameter 
21e80 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76  on F or if the v
21e90 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65  alue of P is doe
21ea0 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20  s not match any 
21eb0 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c  of the.** above,
21ec0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
21ed0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
21ee0 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e   returns (B!=0).
21ef0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
21f00 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50  e3_uri_int64(F,P
21f10 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76  ,D) routine conv
21f20 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f  erts the value o
21f30 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34  f P into a.** 64
21f40 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65  -bit signed inte
21f50 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ger and returns 
21f60 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72  that integer, or
21f70 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74   D if P does not
21f80 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74  .** exist.  If t
21f90 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
21fa0 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
21fb0 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72   than an integer
21fc0 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69  , then.** zero i
21fd0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a  s returned..** .
21fe0 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c  ** If F is a NUL
21ff0 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
22000 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
22010 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
22020 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73  ns NULL and.** s
22030 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
22040 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e  an(F,P,B) return
22050 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f  s B.  If F is no
22060 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  t a NULL pointer
22070 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61   and.** is not a
22080 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70   database file p
22090 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  athname pointer 
220a0 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73  that SQLite pass
220b0 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65  ed into the xOpe
220c0 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c  n.** VFS method,
220d0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
220e0 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69  or of this routi
220f0 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20  ne is undefined 
22100 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20  and probably.** 
22110 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a  undesirable..*/.
22120 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
22130 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75   char *sqlite3_u
22140 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e  ri_parameter(con
22150 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61  st char *zFilena
22160 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  me, const char *
22170 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f  zParam);.SQLITE_
22180 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22190 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73  uri_boolean(cons
221a0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63  t char *zFile, c
221b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61  onst char *zPara
221c0 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29  m, int bDefault)
221d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
221e0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
221f0 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
22200 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
22210 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
22220 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
22230 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
22240 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
22250 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
22260 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
22270 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
22280 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
22290 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
222a0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
222b0 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
222c0 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
222d0 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
222e0 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
222f0 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
22300 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
22310 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
22320 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
22330 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
22340 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
22350 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
22360 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
22370 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
22380 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
22390 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65    ^The sqlite3_e
223a0 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
223b0 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
223c0 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
223d0 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
223e0 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
223f0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
22400 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
22410 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
22420 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
22430 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
22440 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
22450 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
22460 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
22470 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
22480 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
22490 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
224a0 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
224b0 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
224c0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
224d0 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
224e0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
224f0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
22500 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
22510 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
22520 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
22530 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
22540 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
22550 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
22560 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
22570 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
22580 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
22590 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
225a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
225b0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
225c0 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
225d0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
225e0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
225f0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
22600 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
22610 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
22620 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
22630 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
22640 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
22650 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
22660 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
22670 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
22680 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
22690 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
226a0 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
226b0 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
226c0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
226d0 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
226e0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
226f0 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
22700 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
22710 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
22720 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
22730 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
22740 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
22750 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
22760 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
22770 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
22780 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
22790 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
227a0 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
227b0 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
227c0 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
227d0 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
227e0 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
227f0 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
22800 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
22810 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
22820 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
22830 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
22840 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22850 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
22860 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
22870 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
22880 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
22890 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
228a0 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
228b0 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
228c0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
228d0 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
228e0 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
228f0 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
22900 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
22910 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
22920 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
22930 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
22940 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
22950 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
22960 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
22970 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
22980 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
22990 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
229a0 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
229b0 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
229c0 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
229d0 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
229e0 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f   set..*/.SQLITE_
229f0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
22a00 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
22a10 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
22a20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
22a30 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
22a40 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49  lite3 *db);.SQLI
22a50 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
22a60 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  r *sqlite3_errms
22a70 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  g(sqlite3*);.SQL
22a80 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
22a90 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  id *sqlite3_errm
22aa0 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a  sg16(sqlite3*);.
22ab0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
22ac0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
22ad0 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a  rrstr(int);../*.
22ae0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
22af0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
22b00 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
22b10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
22b20 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
22b30 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
22b40 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
22b50 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
22b60 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
22b70 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
22b80 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
22b90 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
22ba0 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
22bb0 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
22bc0 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
22bd0 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
22be0 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
22bf0 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
22c00 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
22c10 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
22c20 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
22c30 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
22c40 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
22c50 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
22c60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22c70 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
22c80 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
22c90 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
22ca0 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
22cb0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
22cc0 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
22cd0 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
22ce0 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
22cf0 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
22d00 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
22d10 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
22d20 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
22d30 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
22d40 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
22d50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
22d60 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
22d70 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
22d80 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
22d90 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
22da0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
22db0 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
22dc0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
22dd0 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
22de0 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
22df0 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
22e00 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
22e10 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
22e20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
22e30 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
22e40 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
22e50 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
22e60 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
22e70 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
22e80 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
22e90 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
22ea0 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
22eb0 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
22ec0 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
22ed0 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
22ee0 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
22ef0 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
22f00 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
22f10 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
22f20 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
22f30 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
22f40 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
22f50 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
22f60 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
22f70 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
22f80 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
22f90 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
22fa0 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
22fb0 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
22fc0 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
22fd0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
22fe0 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
22ff0 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
23000 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
23010 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
23020 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
23030 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
23040 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
23050 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
23060 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
23070 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
23080 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
23090 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
230a0 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
230b0 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
230c0 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
230d0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
230e0 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
230f0 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
23100 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
23110 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
23120 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
23130 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
23140 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
23150 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
23160 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
23170 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
23180 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
23190 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
231a0 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
231b0 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
231c0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
231d0 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
231e0 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
231f0 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
23200 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
23210 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
23220 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
23230 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
23240 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
23250 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
23260 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
23270 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
23280 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
23290 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
232a0 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
232b0 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
232c0 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
232d0 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
232e0 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
232f0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
23300 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
23310 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
23320 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
23330 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
23340 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
23350 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
23360 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
23370 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
23380 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
23390 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
233a0 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
233b0 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
233c0 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
233d0 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
233e0 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
233f0 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
23400 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
23410 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
23420 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
23430 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
23440 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
23450 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
23460 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
23470 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
23480 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
23490 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
234a0 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
234b0 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
234c0 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
234d0 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
234e0 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
234f0 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
23500 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
23510 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
23520 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
23530 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
23540 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
23550 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
23560 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
23570 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
23580 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
23590 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
235a0 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
235b0 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
235c0 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
235d0 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
235e0 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
235f0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
23600 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
23610 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
23620 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
23630 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d   int sqlite3_lim
23640 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
23650 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
23660 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23670 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
23680 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
23690 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
236a0 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
236b0 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
236c0 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
236d0 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
236e0 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
236f0 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
23700 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
23710 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
23720 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
23730 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
23740 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
23750 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
23760 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
23770 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
23780 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
23790 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
237a0 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
237b0 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
237c0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
237d0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
237e0 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
237f0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
23800 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
23810 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
23820 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
23830 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
23840 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
23850 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
23860 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
23870 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
23880 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
23890 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
238a0 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
238b0 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
238c0 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
238d0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
238e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
238f0 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
23900 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
23910 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
23920 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
23930 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
23940 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
23950 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
23960 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
23970 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
23980 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
23990 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
239a0 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
239b0 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
239c0 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
239d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
239e0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
239f0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
23a00 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
23a10 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
23a20 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
23a30 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
23a40 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
23a50 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
23a60 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
23a70 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
23a80 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
23a90 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
23aa0 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
23ab0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
23ac0 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
23ad0 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
23ae0 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
23af0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
23b00 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
23b10 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
23b20 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
23b30 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
23b40 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
23b50 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
23b60 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
23b70 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
23b80 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
23b90 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
23ba0 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20    This limit is 
23bb0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  not currently.**
23bc0 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67   enforced, thoug
23bd0 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  h that might be 
23be0 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75  added in some fu
23bf0 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
23c00 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29  ** SQLite.</dd>)
23c10 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
23c20 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
23c30 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
23c40 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
23c50 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
23c60 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
23c70 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
23c80 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
23c90 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
23ca0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
23cb0 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
23cc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
23cd0 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
23ce0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
23cf0 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
23d00 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
23d10 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
23d20 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
23d30 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
23d40 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
23d50 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
23d60 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
23d70 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
23d80 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
23d90 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
23da0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
23db0 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
23dc0 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
23dd0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
23de0 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
23df0 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
23e00 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
23e10 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
23e20 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
23e30 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
23e40 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
23e50 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
23e60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
23e70 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
23e80 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
23e90 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
23ea0 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
23eb0 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
23ec0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
23ed0 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
23ee0 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
23ef0 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
23f00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23f10 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
23f20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23f30 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
23f40 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
23f50 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
23f60 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
23f70 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
23f80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23f90 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
23fa0 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
23fb0 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
23fc0 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
23fd0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
23fe0 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
23ff0 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
24000 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
24010 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
24020 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
24030 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
24040 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
24050 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
24060 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
24070 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
24080 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
24090 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
240a0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
240b0 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
240c0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
240d0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
240e0 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
240f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
24100 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
24110 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f             10../
24120 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
24130 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
24140 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
24150 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
24160 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
24170 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
24180 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
24190 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
241a0 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
241b0 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
241c0 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
241d0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
241e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
241f0 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
24200 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
24210 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
24220 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
24230 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
24240 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
24250 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
24260 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
24270 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
24280 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
24290 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
242a0 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
242b0 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
242c0 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
242d0 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
242e0 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
242f0 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
24300 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
24310 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
24320 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
24330 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
24340 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
24350 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
24360 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
24370 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
24380 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
24390 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
243a0 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
243b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
243c0 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
243d0 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
243e0 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
243f0 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
24400 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
24410 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
24420 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
24430 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
24440 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d  e maximum.** num
24450 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65  ber of  bytes re
24460 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
24470 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
24480 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
24490 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
244a0 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
244b0 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
244c0 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
244d0 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
244e0 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
244f0 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
24500 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
24510 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
24520 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
24530 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
24540 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
24550 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
24560 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
24570 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
24580 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
24590 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
245a0 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
245b0 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
245c0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
245d0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
245e0 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
245f0 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
24600 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68  ator bytes as th
24610 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20  is saves SQLite 
24620 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a  from having to.*
24630 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  * make a copy of
24640 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
24650 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  g..**.** ^If pzT
24660 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
24670 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
24680 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
24690 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
246a0 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
246b0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
246c0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
246d0 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
246e0 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
246f0 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
24700 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
24710 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
24720 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
24730 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
24740 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
24750 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
24760 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
24770 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
24780 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
24790 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
247a0 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
247b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
247c0 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
247d0 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
247e0 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
247f0 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
24800 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
24810 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
24820 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
24830 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
24840 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
24850 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
24860 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
24870 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
24880 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
24890 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
248a0 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
248b0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
248c0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
248d0 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
248e0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
248f0 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
24900 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
24910 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
24920 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
24930 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
24940 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
24950 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
24960 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
24970 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
24980 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
24990 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
249a0 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
249b0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
249c0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
249d0 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
249e0 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
249f0 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
24a00 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
24a10 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
24a20 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
24a30 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
24a40 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
24a50 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
24a60 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
24a70 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
24a80 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
24a90 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
24aa0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
24ab0 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
24ac0 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
24ad0 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
24ae0 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
24af0 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
24b00 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
24b10 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
24b20 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
24b30 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
24b40 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
24b50 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
24b60 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
24b70 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
24b80 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
24b90 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
24ba0 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
24bb0 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
24bc0 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
24bd0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
24be0 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
24bf0 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
24c00 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a  o run it again..
24c10 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
24c20 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
24c30 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
24c40 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
24c50 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
24c60 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
24c70 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
24c80 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
24c90 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
24ca0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
24cb0 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
24cc0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
24cd0 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
24ce0 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
24cf0 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
24d00 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
24d10 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
24d20 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
24d30 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
24d40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
24d50 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
24d60 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
24d70 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
24d80 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
24d90 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
24da0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
24db0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
24dc0 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
24dd0 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
24de0 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
24df0 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
24e00 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
24e10 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
24e20 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
24e30 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
24e40 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
24e50 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
24e60 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
24e70 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
24e80 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
24e90 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
24ea0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
24eb0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
24ec0 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
24ed0 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
24ee0 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
24ef0 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
24f00 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
24f10 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
24f20 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
24f30 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
24f40 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
24f50 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
24f60 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
24f70 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
24f80 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
24f90 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
24fa0 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
24fb0 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
24fc0 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
24fd0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
24fe0 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
24ff0 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
25000 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
25010 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
25020 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
25030 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
25040 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
25050 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
25060 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70  ABLE_STAT3] comp
25070 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
25080 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74  is enabled..** t
25090 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  he .** </li>.** 
250a0 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ol>.*/.SQLITE_
250b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
250c0 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
250d0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
250e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
250f0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
25100 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
25110 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
25120 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
25130 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
25140 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
25150 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
25160 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
25170 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
25180 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
25190 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
251a0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
251b0 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
251c0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
251d0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
251e0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
251f0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
25200 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
25210 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
25220 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
25230 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
25240 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
25250 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
25260 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
25270 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
25280 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
25290 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
252a0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
252b0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
252c0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
252d0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
252e0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
252f0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
25300 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
25310 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
25320 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
25330 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
25340 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
25350 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
25360 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
25370 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
25380 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
25390 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
253a0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
253b0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
253c0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
253d0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
253e0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
253f0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
25400 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
25410 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
25420 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
25430 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
25440 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
25450 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
25460 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
25470 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
25480 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
25490 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
254a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
254b0 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
254c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
254d0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
254e0 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
254f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
25500 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
25510 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
25520 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
25530 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
25540 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
25550 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
25560 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
25570 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
25580 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
25590 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
255a0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
255b0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
255c0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
255d0 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
255e0 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
255f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
25600 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
25610 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
25620 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
25630 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
25640 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
25650 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
25660 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
25670 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
25680 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
25690 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
256a0 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
256b0 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
256c0 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
256d0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
256e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
256f0 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  v2()]..*/.SQLITE
25700 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
25710 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
25720 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
25730 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
25740 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
25750 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
25760 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
25770 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
25780 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
25790 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
257a0 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
257b0 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
257c0 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
257d0 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
257e0 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
257f0 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
25800 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
25810 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
25820 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
25830 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
25840 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
25850 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
25860 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
25870 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
25880 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
25890 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
258a0 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
258b0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
258c0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
258d0 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
258e0 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
258f0 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
25900 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
25910 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
25920 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
25930 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
25940 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
25950 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
25960 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
25970 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
25980 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
25990 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
259a0 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
259b0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
259c0 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
259d0 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
259e0 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
259f0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
25a00 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
25a10 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
25a20 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
25a30 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
25a40 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
25a50 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
25a60 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
25a70 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
25a80 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
25a90 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
25aa0 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
25ab0 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
25ac0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
25ad0 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
25ae0 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
25af0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
25b00 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
25b10 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
25b20 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
25b30 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
25b40 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
25b50 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
25b60 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
25b70 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
25b80 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
25b90 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
25ba0 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
25bb0 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
25bc0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
25bd0 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
25be0 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
25bf0 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
25c00 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
25c10 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
25c20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
25c30 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
25c40 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
25c50 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
25c60 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
25c70 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
25c80 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
25c90 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
25ca0 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
25cb0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
25cc0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25cd0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
25ce0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
25cf0 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
25d00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
25d10 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
25d20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
25d30 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
25d40 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
25d50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25d60 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
25d70 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
25d80 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
25d90 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
25da0 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
25db0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
25dc0 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
25dd0 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
25de0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
25df0 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
25e00 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
25e10 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
25e20 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
25e30 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
25e40 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
25e50 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
25e60 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
25e70 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
25e80 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
25e90 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
25ea0 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
25eb0 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
25ec0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
25ed0 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
25ee0 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
25ef0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
25f00 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
25f10 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
25f20 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
25f30 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
25f40 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
25f50 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
25f60 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
25f70 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
25f80 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
25f90 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
25fa0 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
25fb0 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
25fc0 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
25fd0 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
25fe0 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
25ff0 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
26000 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
26010 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45   open..*/.SQLITE
26020 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
26030 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
26040 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
26050 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
26060 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
26070 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
26080 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
26090 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
260a0 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
260b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
260c0 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
260d0 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
260e0 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
260f0 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
26100 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
26110 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
26120 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
26130 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
26140 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
26150 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
26160 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
26170 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
26180 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
26190 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
261a0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
261b0 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
261c0 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
261d0 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
261e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
261f0 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
26200 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
26210 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
26220 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
26230 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
26240 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
26250 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
26260 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
26270 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
26280 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
26290 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
262a0 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
262b0 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
262c0 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
262d0 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
262e0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
262f0 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
26300 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
26310 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
26320 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
26330 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
26340 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
26350 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
26360 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
26370 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
26380 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
26390 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
263a0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
263b0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
263c0 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
263d0 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
263e0 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
263f0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
26400 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
26410 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
26420 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
26430 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
26440 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
26450 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
26460 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
26470 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
26480 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
26490 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
264a0 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
264b0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
264c0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
264d0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
264e0 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
264f0 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
26500 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
26510 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
26520 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
26530 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
26540 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
26550 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
26560 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
26570 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
26580 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
26590 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
265a0 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
265b0 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
265c0 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
265d0 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
265e0 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
265f0 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
26600 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
26610 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
26620 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
26630 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
26640 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
26650 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
26660 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
26670 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
26680 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
26690 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
266a0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
266b0 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
266c0 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
266d0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
266e0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
266f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
26700 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
26710 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
26720 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
26730 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
26740 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
26750 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
26760 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
26770 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
26780 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
26790 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
267a0 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
267b0 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
267c0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
267d0 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
267e0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
267f0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
26800 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
26810 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
26820 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
26830 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
26840 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
26850 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
26860 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
26870 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
26880 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
26890 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
268a0 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
268b0 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
268c0 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
268d0 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
268e0 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
268f0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
26900 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
26910 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
26920 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
26930 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
26940 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
26950 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
26960 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
26970 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
26980 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
26990 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
269a0 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
269b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
269c0 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
269d0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
269e0 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
269f0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
26a00 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
26a10 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
26a20 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
26a30 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
26a40 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
26a50 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
26a60 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
26a70 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
26a80 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
26a90 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
26aa0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
26ab0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
26ac0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
26ad0 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
26ae0 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
26af0 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
26b00 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
26b10 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
26b20 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
26b30 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
26b40 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
26b50 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
26b60 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
26b70 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
26b80 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
26b90 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
26ba0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
26bb0 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
26bc0 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
26bd0 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
26be0 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
26bf0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
26c00 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
26c10 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
26c20 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
26c30 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
26c40 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
26c50 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
26c60 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
26c70 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
26c80 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
26c90 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
26ca0 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
26cb0 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
26cc0 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
26cd0 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
26ce0 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
26cf0 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
26d00 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
26d10 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
26d20 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
26d30 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
26d40 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
26d50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
26d60 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
26d70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
26d80 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
26d90 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
26da0 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
26db0 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
26dc0 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
26dd0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26de0 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
26df0 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
26e00 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
26e10 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
26e20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
26e30 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
26e40 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
26e50 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
26e60 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
26e70 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
26e80 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
26e90 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
26ea0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
26eb0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
26ec0 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
26ed0 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
26ee0 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
26ef0 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
26f00 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
26f10 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
26f20 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
26f30 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
26f40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
26f50 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
26f60 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
26f70 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
26f80 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
26f90 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
26fa0 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
26fb0 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
26fc0 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
26fd0 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
26fe0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
26ff0 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
27000 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
27010 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
27020 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
27030 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
27040 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
27050 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
27060 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
27070 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
27080 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
27090 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
270a0 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
270b0 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
270c0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
270d0 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
270e0 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
270f0 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
27100 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
27110 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
27120 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
27130 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
27140 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
27150 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
27160 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
27170 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
27180 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
27190 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
271a0 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
271b0 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
271c0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
271d0 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
271e0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
271f0 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
27200 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
27210 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
27220 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
27230 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
27240 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
27250 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
27260 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
27270 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
27280 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
27290 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
272a0 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
272b0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
272c0 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65  then that parame
272d0 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
272e0 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
272f0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
27300 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
27310 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
27320 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
27330 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
27340 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
27350 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
27360 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
27370 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
27380 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
27390 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
273a0 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
273b0 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
273c0 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
273d0 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
273e0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
273f0 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
27400 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
27410 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
27420 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
27430 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
27440 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
27450 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
27460 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
27470 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
27480 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
27490 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
274a0 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
274b0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
274c0 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
274d0 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
274e0 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
274f0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
27500 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
27510 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
27520 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
27530 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
27540 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
27550 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  b(),.** sqlite3_
27560 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20  bind_text(), or 
27570 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
27580 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a  t16() fails.  .*
27590 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
275a0 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
275b0 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
275c0 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
275d0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
275e0 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
275f0 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
27600 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
27610 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
27620 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
27630 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
27640 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
27650 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
27660 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
27670 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
27680 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
27690 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
276a0 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
276b0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
276c0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
276d0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
276e0 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
276f0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
27700 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
27710 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
27720 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
27730 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
27740 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
27750 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
27760 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
27770 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
27780 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
27790 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
277a0 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
277b0 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
277c0 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
277d0 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
277e0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
277f0 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
27800 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
27810 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
27820 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
27830 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
27840 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
27850 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
27860 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
27870 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
27880 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
27890 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
278a0 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
278b0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
278c0 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
278d0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
278e0 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
278f0 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
27900 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
27910 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
27920 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
27930 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
27940 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
27950 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
27960 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
27970 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
27980 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
27990 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
279a0 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
279b0 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
279c0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
279d0 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
279e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
279f0 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
27a00 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
27a10 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
27a20 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
27a30 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
27a40 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
27a50 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
27a60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
27a70 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
27a80 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
27a90 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
27aa0 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
27ab0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
27ac0 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
27ad0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
27ae0 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
27af0 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
27b00 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
27b10 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
27b20 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
27b30 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
27b40 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
27b50 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
27b60 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
27b70 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
27b80 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
27b90 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
27ba0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
27bb0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
27bc0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
27bd0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
27be0 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
27bf0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
27c00 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
27c10 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
27c20 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
27c30 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
27c40 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
27c50 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
27c60 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
27c70 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
27c80 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
27c90 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27ca0 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49  t, double);.SQLI
27cb0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
27cc0 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
27cd0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
27ce0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
27cf0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
27d00 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
27d10 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
27d20 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49  te3_int64);.SQLI
27d30 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
27d40 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
27d50 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
27d60 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
27d70 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
27d80 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
27d90 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
27da0 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
27db0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
27dc0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
27dd0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
27de0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27df0 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
27e00 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
27e10 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
27e20 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
27e30 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
27e40 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
27e50 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
27e60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
27e70 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
27e80 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
27e90 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
27ea0 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
27eb0 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
27ec0 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
27ed0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
27ee0 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
27ef0 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
27f00 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
27f10 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
27f20 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
27f30 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
27f40 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
27f50 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
27f60 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
27f70 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
27f80 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
27f90 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
27fa0 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
27fb0 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
27fc0 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
27fd0 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
27fe0 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
27ff0 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
28000 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
28010 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
28020 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
28030 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
28040 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
28050 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
28060 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
28070 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
28080 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
28090 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
280a0 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
280b0 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
280c0 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
280d0 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
280e0 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
280f0 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
28100 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
28110 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
28120 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
28130 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28140 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
28150 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
28160 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
28170 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
28180 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
28190 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
281a0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
281b0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
281c0 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
281d0 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
281e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
281f0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28200 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
28210 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
28220 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
28230 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
28240 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
28250 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28260 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
28270 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
28280 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
28290 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
282a0 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
282b0 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
282c0 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
282d0 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
282e0 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
282f0 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
28300 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
28310 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
28320 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
28330 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
28340 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
28350 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
28360 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
28370 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
28380 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
28390 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
283a0 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
283b0 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
283c0 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
283d0 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
283e0 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
283f0 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
28400 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
28410 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
28420 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
28430 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
28440 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
28450 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
28460 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
28470 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
28480 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
28490 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
284a0 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
284b0 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
284c0 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
284d0 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
284e0 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
284f0 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
28500 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
28510 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
28520 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28530 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
28540 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
28550 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
28560 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
28570 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
28580 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
28590 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
285a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
285b0 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
285c0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
285d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
285e0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
285f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
28600 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
28610 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
28620 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
28630 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
28640 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
28650 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
28660 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
28670 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
28680 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
28690 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
286a0 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
286b0 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
286c0 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
286d0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
286e0 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
286f0 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
28700 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
28710 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
28720 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
28730 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
28740 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
28750 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
28760 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
28770 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
28780 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
28790 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
287a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
287b0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
287c0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
287d0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
287e0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
287f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
28800 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
28810 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
28820 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28830 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
28840 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28850 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
28860 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
28870 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
28880 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
28890 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
288a0 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
288b0 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
288c0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43  atement.**.** ^C
288d0 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
288e0 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
288f0 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
28900 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
28910 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
28920 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
28930 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
28940 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28950 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
28960 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
28970 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
28980 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
28990 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
289a0 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
289b0 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
289c0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
289d0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
289e0 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
289f0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
28a00 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
28a10 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
28a20 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
28a30 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
28a40 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
28a50 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
28a60 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
28a70 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
28a80 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
28a90 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
28aa0 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
28ab0 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
28ac0 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ATE])..**.** See
28ad0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
28ae0 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
28af0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
28b00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
28b10 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
28b20 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
28b30 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
28b40 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
28b50 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
28b60 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
28b70 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
28b80 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
28b90 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
28ba0 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
28bb0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
28bc0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
28bd0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
28be0 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
28bf0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
28c00 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
28c10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
28c20 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
28c30 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28c40 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
28c50 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
28c60 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
28c70 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
28c80 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
28c90 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
28ca0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
28cb0 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
28cc0 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
28cd0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
28ce0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
28cf0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
28d00 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
28d10 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
28d20 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
28d30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
28d40 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
28d50 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
28d60 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
28d70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
28d80 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
28d90 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
28da0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
28db0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
28dc0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
28dd0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
28de0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
28df0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
28e00 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
28e10 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
28e20 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
28e30 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
28e40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
28e50 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
28e60 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
28e70 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
28e80 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
28e90 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
28ea0 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
28eb0 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
28ec0 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
28ed0 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
28ee0 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
28ef0 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
28f00 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
28f10 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
28f20 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
28f30 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
28f40 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
28f50 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
28f60 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
28f70 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
28f80 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
28f90 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
28fa0 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
28fb0 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
28fc0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
28fd0 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
28fe0 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
28ff0 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
29000 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
29010 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51   the next..*/.SQ
29020 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
29030 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
29040 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
29050 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
29060 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
29070 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
29080 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
29090 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
290a0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
290b0 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
290c0 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
290d0 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
290e0 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
290f0 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
29100 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
29110 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
29120 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
29130 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
29140 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
29150 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
29160 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
29170 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
29180 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
29190 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
291a0 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
291b0 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
291c0 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
291d0 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
291e0 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
291f0 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
29200 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
29210 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
29220 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
29230 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
29240 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
29250 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
29260 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
29270 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
29280 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
29290 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
292a0 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
292b0 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
292c0 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
292d0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
292e0 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
292f0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
29300 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
29310 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
29320 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
29330 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29340 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
29350 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
29360 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
29370 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
29380 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
29390 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
293a0 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
293b0 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
293c0 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
293d0 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
293e0 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
293f0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
29400 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
29410 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
29420 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
29430 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
29440 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29450 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
29460 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
29470 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
29480 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
29490 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
294a0 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
294b0 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
294c0 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
294d0 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
294e0 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
294f0 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
29500 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
29510 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
29520 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
29530 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
29540 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
29550 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
29560 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
29570 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
29580 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
29590 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
295a0 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
295b0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
295c0 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
295d0 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
295e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
295f0 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
29600 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
29610 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
29620 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
29630 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
29640 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
29650 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
29660 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
29670 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
29680 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
29690 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
296a0 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
296b0 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
296c0 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
296d0 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
296e0 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
296f0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
29700 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
29710 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
29720 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
29730 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
29740 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
29750 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
29760 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
29770 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
29780 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
29790 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
297a0 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
297b0 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
297c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
297d0 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
297e0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
297f0 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
29800 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
29810 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
29820 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
29830 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
29840 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
29850 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
29860 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
29870 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
29880 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
29890 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
298a0 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
298b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
298c0 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
298d0 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
298e0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
298f0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
29900 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51  undefined..*/.SQ
29910 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
29920 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
29930 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
29940 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
29950 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
29960 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
29970 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
29980 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
29990 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
299a0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
299b0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
299c0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
299d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
299e0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
299f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
29a00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
29a10 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
29a20 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
29a30 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
29a40 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
29a50 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
29a60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
29a70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
29a80 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
29a90 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
29aa0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
29ab0 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
29ac0 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
29ad0 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
29ae0 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
29af0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
29b00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
29b10 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
29b20 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
29b30 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
29b40 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
29b50 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
29b60 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
29b70 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
29b80 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
29b90 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
29ba0 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
29bb0 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
29bc0 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
29bd0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
29be0 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
29bf0 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
29c00 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
29c10 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
29c20 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
29c30 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
29c40 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
29c50 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
29c60 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
29c70 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
29c80 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
29c90 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
29ca0 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
29cb0 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
29cc0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
29cd0 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
29ce0 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
29cf0 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
29d00 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
29d10 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
29d20 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
29d30 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
29d40 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
29d50 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
29d60 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
29d70 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
29d80 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
29d90 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
29da0 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
29db0 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
29dc0 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
29dd0 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
29de0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
29df0 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
29e00 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
29e10 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
29e20 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
29e30 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
29e40 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
29e50 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
29e60 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
29e70 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
29e80 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
29e90 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
29ea0 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
29eb0 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
29ec0 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
29ed0 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
29ee0 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
29ef0 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
29f00 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
29f10 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
29f20 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
29f30 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
29f40 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  alues..*/.SQLITE
29f50 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
29f60 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
29f70 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
29f80 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
29f90 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
29fa0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
29fb0 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
29fc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
29fd0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29fe0 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
29ff0 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  QL Statement.**.
2a000 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
2a010 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a020 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
2a030 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
2a040 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2a050 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2a060 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2a070 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
2a080 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2a090 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
2a0a0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
2a0b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a0c0 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
2a0d0 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
2a0e0 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
2a0f0 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
2a100 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
2a110 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
2a120 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
2a130 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
2a140 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
2a150 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
2a160 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
2a170 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
2a180 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
2a190 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
2a1a0 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
2a1b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2a1c0 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2a1d0 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
2a1e0 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
2a1f0 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
2a200 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2a210 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2a220 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
2a230 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
2a240 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
2a250 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
2a260 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
2a270 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
2a280 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2a290 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
2a2a0 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
2a2b0 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
2a2c0 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2a2d0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2a2e0 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
2a2f0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
2a300 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
2a310 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
2a320 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
2a330 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
2a340 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2a350 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
2a360 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
2a370 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
2a380 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2a390 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
2a3a0 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
2a3b0 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
2a3c0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
2a3d0 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
2a3e0 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
2a3f0 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
2a400 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
2a410 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
2a420 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
2a430 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
2a440 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
2a450 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
2a460 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
2a470 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2a480 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
2a490 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
2a4a0 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
2a4b0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
2a4c0 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
2a4d0 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
2a4e0 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
2a4f0 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
2a500 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
2a510 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
2a520 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
2a530 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
2a540 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
2a550 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
2a560 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
2a570 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
2a580 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
2a590 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2a5a0 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2a5b0 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
2a5c0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2a5d0 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
2a5e0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
2a5f0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
2a600 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
2a610 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
2a620 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
2a630 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
2a640 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2a650 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
2a660 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
2a670 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
2a680 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
2a690 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
2a6a0 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
2a6b0 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
2a6c0 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
2a6d0 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
2a6e0 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
2a6f0 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
2a700 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
2a710 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
2a720 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
2a730 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
2a740 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
2a750 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
2a760 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
2a770 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
2a780 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
2a790 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
2a7a0 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
2a7b0 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
2a7c0 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
2a7d0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2a7e0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2a7f0 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
2a800 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
2a810 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
2a820 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
2a830 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
2a840 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
2a850 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
2a860 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2a870 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
2a880 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2a890 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
2a8a0 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
2a8b0 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
2a8c0 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
2a8d0 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
2a8e0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2a8f0 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
2a900 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2a910 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
2a920 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2a930 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
2a940 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2a950 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
2a960 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
2a970 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
2a980 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2a990 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
2a9a0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
2a9b0 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
2a9c0 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
2a9d0 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
2a9e0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2a9f0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2aa00 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
2aa10 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
2aa20 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2aa30 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
2aa40 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
2aa50 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
2aa60 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
2aa70 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
2aa80 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
2aa90 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
2aaa0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2aab0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
2aac0 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
2aad0 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
2aae0 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
2aaf0 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
2ab00 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
2ab10 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2ab20 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
2ab30 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
2ab40 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2ab50 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
2ab60 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
2ab70 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2ab80 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
2ab90 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
2aba0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
2abb0 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
2abc0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
2abd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2abe0 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
2abf0 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
2ac00 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
2ac10 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2ac20 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
2ac30 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
2ac40 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
2ac50 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
2ac60 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
2ac70 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e  after version 3.
2ac80 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
2ac90 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20  step() began.** 
2aca0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2acb0 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61  _reset()] automa
2acc0 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
2acd0 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
2ace0 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75  her.** than retu
2acf0 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49  rning [SQLITE_MI
2ad00 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20  SUSE].  This is 
2ad10 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61  not considered a
2ad20 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
2ad30 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20  * break because 
2ad40 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  any application 
2ad50 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76  that ever receiv
2ad60 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53  es an SQLITE_MIS
2ad70 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20  USE error.** is 
2ad80 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69  broken by defini
2ad90 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49  tion.  The [SQLI
2ada0 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45  TE_OMIT_AUTORESE
2adb0 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
2adc0 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65  option.** can be
2add0 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65   used to restore
2ade0 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
2adf0 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  vior..**.** <b>G
2ae00 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
2ae10 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
2ae20 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2ae30 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
2ae40 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
2ae50 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
2ae60 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
2ae70 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2ae80 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
2ae90 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
2aea0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
2aeb0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
2aec0 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
2aed0 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
2aee0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2aef0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2af00 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
2af10 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
2af20 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
2af30 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
2af40 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
2af50 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
2af60 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
2af70 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
2af80 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
2af90 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
2afa0 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
2afb0 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
2afc0 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
2afd0 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
2afe0 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
2aff0 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2b000 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2b010 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2b020 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
2b030 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
2b040 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
2b050 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2b060 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
2b070 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
2b080 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
2b090 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2b0a0 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
2b0b0 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
2b0c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2b0d0 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
2b0e0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2b0f0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
2b100 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2b110 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
2b120 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2b130 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2b140 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2b150 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
2b160 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b170 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2b180 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2b190 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2b1a0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2b1b0 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
2b1c0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2b1d0 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
2b1e0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2b1f0 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
2b200 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
2b210 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
2b220 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
2b230 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
2b240 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
2b250 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
2b260 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
2b270 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
2b280 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
2b290 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
2b2a0 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
2b2b0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2b2c0 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
2b2d0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
2b2e0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2b2f0 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
2b300 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2b310 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2b320 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
2b330 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
2b340 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2b350 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2b360 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
2b370 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2b380 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
2b390 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
2b3a0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2b3b0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2b3c0 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
2b3d0 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
2b3e0 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
2b3f0 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
2b400 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
2b410 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
2b420 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
2b430 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
2b440 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
2b450 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
2b460 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
2b470 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2b480 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2b490 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2b4a0 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )].*/.SQLITE_API
2b4b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74   int sqlite3_dat
2b4c0 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
2b4d0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2b4e0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2b4f0 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
2b500 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
2b510 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
2b520 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
2b530 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
2b540 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
2b550 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
2b560 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2b570 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
2b580 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
2b590 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
2b5a0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2b5b0 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
2b5c0 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
2b5d0 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
2b5e0 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
2b5f0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
2b600 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
2b610 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
2b620 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2b630 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
2b640 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
2b650 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
2b660 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
2b670 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
2b680 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
2b690 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
2b6a0 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
2b6b0 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
2b6c0 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
2b6d0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
2b6e0 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
2b6f0 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
2b700 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
2b710 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2b720 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
2b730 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
2b740 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2b750 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
2b760 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
2b770 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
2b780 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
2b790 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2b7a0 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
2b7b0 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
2b7c0 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
2b7d0 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
2b7e0 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
2b7f0 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
2b800 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
2b810 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
2b820 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2b830 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
2b840 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
2b850 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20  he "result set" 
2b860 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2b870 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2b880 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2b890 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
2b8a0 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
2b8b0 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
2b8c0 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
2b8d0 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
2b8e0 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
2b8f0 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
2b900 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
2b910 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b920 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
2b930 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
2b940 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
2b950 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
2b960 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2b970 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2b980 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
2b990 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
2b9a0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2b9b0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2b9c0 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
2b9d0 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
2b9e0 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
2b9f0 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
2ba00 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
2ba10 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2ba20 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
2ba30 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
2ba40 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2ba50 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
2ba60 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
2ba70 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
2ba80 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
2ba90 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
2baa0 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2bab0 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
2bac0 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
2bad0 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
2bae0 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
2baf0 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
2bb00 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
2bb10 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
2bb20 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
2bb30 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2bb40 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
2bb50 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2bb60 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2bb70 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
2bb80 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
2bb90 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2bba0 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
2bbb0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2bbc0 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
2bbd0 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
2bbe0 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
2bbf0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2bc00 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
2bc10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2bc20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2bc30 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
2bc40 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
2bc50 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2bc60 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
2bc70 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2bc80 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
2bc90 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2bca0 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
2bcb0 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2bcc0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2bcd0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2bce0 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
2bcf0 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
2bd00 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
2bd10 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
2bd20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2bd30 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
2bd40 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2bd50 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2bd60 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2bd70 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
2bd80 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2bd90 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2bda0 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
2bdb0 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
2bdc0 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
2bdd0 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
2bde0 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
2bdf0 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
2be00 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
2be10 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
2be20 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
2be30 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
2be40 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
2be50 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
2be60 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
2be70 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2be80 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
2be90 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
2bea0 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
2beb0 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
2bec0 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
2bed0 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
2bee0 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2bef0 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
2bf00 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2bf10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2bf20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
2bf30 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
2bf40 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
2bf50 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
2bf60 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
2bf70 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
2bf80 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
2bf90 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
2bfa0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2bfb0 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2bfc0 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
2bfd0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2bfe0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
2bff0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2c000 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2c010 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2c020 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2c030 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2c040 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2c050 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2c060 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
2c070 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
2c080 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
2c090 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
2c0a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2c0b0 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
2c0c0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
2c0d0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
2c0e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2c0f0 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
2c100 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
2c110 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
2c120 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
2c130 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
2c140 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
2c150 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
2c160 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
2c170 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2c180 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
2c190 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c1a0 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
2c1b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2c1c0 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
2c1d0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2c1e0 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
2c1f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2c200 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
2c210 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2c220 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2c230 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
2c240 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2c250 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
2c260 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
2c270 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2c280 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
2c290 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
2c2a0 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
2c2b0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2c2c0 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
2c2d0 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2c2e0 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
2c2f0 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
2c300 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2c310 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2c320 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2c330 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2c340 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
2c350 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2c360 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2c370 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2c380 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2c390 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2c3a0 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2c3b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c3c0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2c3d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
2c3e0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
2c3f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2c400 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
2c410 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c420 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
2c430 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
2c440 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
2c450 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
2c460 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
2c470 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
2c480 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
2c490 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2c4a0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
2c4b0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2c4c0 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
2c4d0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
2c4e0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
2c4f0 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
2c500 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
2c510 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
2c520 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
2c530 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2c540 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
2c550 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2c560 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
2c570 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
2c580 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
2c590 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
2c5a0 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
2c5b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2c5c0 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
2c5d0 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
2c5e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
2c5f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63  **.** ^The objec
2c600 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
2c610 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2c620 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
2c630 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2c640 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2c650 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
2c660 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2c670 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
2c680 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
2c690 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
2c6a0 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
2c6b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
2c6c0 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
2c6d0 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2c6e0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2c6f0 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
2c700 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2c710 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
2c720 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
2c730 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
2c740 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
2c750 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
2c760 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
2c770 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2c780 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
2c790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2c7a0 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
2c7b0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2c7c0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
2c7d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
2c7e0 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
2c7f0 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
2c800 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
2c810 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
2c820 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
2c830 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
2c840 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
2c850 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
2c860 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
2c870 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
2c880 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
2c890 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
2c8a0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
2c8b0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
2c8c0 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
2c8d0 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
2c8e0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
2c8f0 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
2c900 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
2c910 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
2c920 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
2c930 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
2c940 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
2c950 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
2c960 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
2c970 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
2c980 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
2c990 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
2c9a0 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
2c9b0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
2c9c0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2c9d0 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
2c9e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2c9f0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2ca00 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2ca10 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2ca20 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2ca30 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2ca40 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2ca50 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
2ca60 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2ca70 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
2ca80 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2ca90 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
2caa0 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2cab0 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2cac0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2cad0 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2cae0 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
2caf0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2cb00 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
2cb10 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
2cb20 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
2cb30 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2cb40 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2cb50 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
2cb60 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
2cb70 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
2cb80 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
2cb90 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
2cba0 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
2cbb0 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
2cbc0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2cbd0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
2cbe0 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
2cbf0 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
2cc00 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
2cc10 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
2cc20 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
2cc30 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2cc40 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2cc50 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
2cc60 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
2cc70 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2cc80 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
2cc90 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
2cca0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
2ccb0 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
2ccc0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
2ccd0 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
2cce0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
2ccf0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
2cd00 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
2cd10 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
2cd20 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
2cd30 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
2cd40 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
2cd50 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
2cd60 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
2cd70 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2cd80 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
2cd90 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
2cda0 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
2cdb0 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
2cdc0 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
2cdd0 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
2cde0 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
2cdf0 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
2ce00 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
2ce10 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
2ce20 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
2ce30 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
2ce40 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
2ce50 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
2ce60 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
2ce70 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
2ce80 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
2ce90 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
2cea0 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
2ceb0 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
2cec0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2ced0 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
2cee0 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
2cef0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
2cf00 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
2cf10 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2cf20 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
2cf30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2cf40 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
2cf50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2cf60 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
2cf70 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
2cf80 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
2cf90 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
2cfa0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
2cfb0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
2cfc0 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
2cfd0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2cfe0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2cff0 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
2d000 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2d010 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
2d020 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2d030 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
2d040 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
2d050 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
2d060 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
2d070 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
2d080 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
2d090 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2d0a0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
2d0b0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2d0c0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2d0d0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2d0e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d0f0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2d100 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2d110 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2d120 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
2d130 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
2d140 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2d150 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
2d160 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2d170 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2d180 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2d190 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
2d1a0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2d1b0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2d1c0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2d1d0 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
2d1e0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
2d1f0 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
2d200 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
2d210 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
2d220 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
2d230 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
2d240 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
2d250 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
2d260 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
2d270 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2d280 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
2d290 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
2d2a0 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
2d2b0 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
2d2c0 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
2d2d0 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
2d2e0 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
2d2f0 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
2d300 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
2d310 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
2d320 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
2d330 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
2d340 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
2d350 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
2d360 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
2d370 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
2d380 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
2d390 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
2d3a0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
2d3b0 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
2d3c0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
2d3d0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2d3e0 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2d3f0 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
2d400 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2d410 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2d420 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2d430 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2d440 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2d450 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d460 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
2d470 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2d480 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
2d490 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2d4a0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
2d4b0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2d4c0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
2d4d0 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
2d4e0 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
2d4f0 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
2d500 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2d510 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
2d520 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
2d530 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
2d540 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
2d550 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
2d560 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
2d570 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2d580 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
2d590 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d5a0 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
2d5b0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
2d5c0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
2d5d0 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
2d5e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d5f0 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
2d600 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
2d610 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
2d620 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d630 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
2d640 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
2d650 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d660 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
2d670 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2d680 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
2d690 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
2d6a0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
2d6b0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
2d6c0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
2d6d0 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
2d6e0 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
2d6f0 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
2d700 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2d710 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2d720 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2d730 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
2d740 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
2d750 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
2d760 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
2d770 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
2d780 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2d790 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
2d7a0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
2d7b0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
2d7c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2d7d0 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
2d7e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
2d7f0 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
2d800 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
2d810 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
2d820 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2d830 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
2d840 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
2d850 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
2d860 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
2d870 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
2d880 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
2d890 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
2d8a0 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
2d8b0 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
2d8c0 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2d8d0 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
2d8e0 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
2d8f0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2d900 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
2d910 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
2d920 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
2d930 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54  MEM].)^.*/.SQLIT
2d940 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2d950 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2d960 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
2d970 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2d980 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2d990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d9a0 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
2d9b0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2d9c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2d9d0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d9e0 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
2d9f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
2da00 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20  LITE_API double 
2da10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2da20 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2da30 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2da40 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2da50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2da60 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2da70 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2da80 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
2da90 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
2daa0 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
2dab0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2dac0 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  l);.SQLITE_API c
2dad0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
2dae0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2daf0 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
2db00 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2db10 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2db20 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2db30 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
2db40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2db50 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
2db60 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2db70 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
2db80 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2db90 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
2dba0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
2dbb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2dbc0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
2dbd0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
2dbe0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2dbf0 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
2dc00 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
2dc10 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ect.**.** ^The s
2dc20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2dc30 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
2dc40 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
2dc50 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2dc60 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
2dc70 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
2dc80 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
2dc90 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
2dca0 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
2dcb0 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
2dcc0 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
2dcd0 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
2dce0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
2dcf0 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
2dd00 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
2dd10 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2dd20 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
2dd30 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
2dd40 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
2dd50 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2dd60 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
2dd70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
2dd80 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
2dd90 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
2dda0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
2ddb0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
2ddc0 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
2ddd0 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
2dde0 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
2ddf0 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
2de00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2de10 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
2de20 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
2de30 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
2de40 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
2de50 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
2de60 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2de70 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
2de80 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
2de90 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
2dea0 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
2deb0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
2dec0 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
2ded0 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
2dee0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
2def0 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
2df00 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
2df10 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
2df20 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
2df30 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2df40 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
2df50 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
2df60 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
2df70 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
2df80 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
2df90 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
2dfa0 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
2dfb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
2dfc0 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
2dfd0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2dfe0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2dff0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
2e000 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
2e010 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
2e020 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
2e030 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
2e040 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
2e050 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
2e060 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
2e070 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
2e080 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
2e090 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51  orruption..*/.SQ
2e0a0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2e0b0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
2e0c0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2e0d0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e0e0 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
2e0f0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2e100 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
2e110 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
2e120 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2e130 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
2e140 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2e150 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
2e160 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2e170 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
2e180 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
2e190 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
2e1a0 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
2e1b0 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
2e1c0 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
2e1d0 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
2e1e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2e1f0 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
2e200 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
2e210 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
2e220 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
2e230 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
2e240 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
2e250 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
2e260 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2e270 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
2e280 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
2e290 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
2e2a0 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
2e2b0 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
2e2c0 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
2e2d0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2e2e0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2e2f0 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2e300 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2e310 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
2e320 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2e330 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
2e340 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
2e350 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2e360 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
2e370 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
2e380 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
2e390 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2e3a0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
2e3b0 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
2e3c0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2e3d0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2e3e0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2e3f0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2e400 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
2e410 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
2e420 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
2e430 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2e440 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
2e450 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
2e460 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
2e470 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2e480 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
2e490 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
2e4a0 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
2e4b0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
2e4c0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
2e4d0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2e4e0 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54  ent] S..*/.SQLIT
2e4f0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2e500 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
2e510 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2e520 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
2e530 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
2e540 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a  e SQL Functions.
2e550 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
2e560 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
2e570 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59  routines}.** KEY
2e580 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
2e590 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2e5a0 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59  function}.** KEY
2e5b0 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
2e5c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2e5d0 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
2e5e0 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
2e5f0 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
2e600 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
2e610 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
2e620 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
2e630 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
2e640 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
2e650 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
2e660 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
2e670 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
2e680 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
2e690 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
2e6a0 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
2e6b0 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ces between.** t
2e6c0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2e6d0 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  e the text encod
2e6e0 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72  ing expected for
2e6f0 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
2e700 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61  arameter (the na
2e710 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  me of the functi
2e720 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  on being created
2e730 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65  ).** and the pre
2e740 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65  sence or absence
2e750 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72   of a destructor
2e760 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a   callback for.**
2e770 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2e780 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a   data pointer..*
2e790 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2e7a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2e7b0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2e7c0 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
2e7d0 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
2e7e0 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
2e7f0 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c  ed.  ^If an appl
2e800 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72  ication uses mor
2e810 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
2e820 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
2e830 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69  n then applicati
2e840 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2e850 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
2e860 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63   added.** to eac
2e870 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
2e880 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79  ction separately
2e890 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
2e8a0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
2e8b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2e8c0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
2e8d0 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
2e8e0 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54  * redefined.  ^T
2e8f0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
2e900 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
2e910 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e   to 255 bytes in
2e920 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72   a UTF-8.** repr
2e930 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c  esentation, excl
2e940 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
2e950 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  o-terminator.  ^
2e960 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
2e970 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d  me.** length lim
2e980 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62  it is in UTF-8 b
2e990 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63  ytes, not charac
2e9a0 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20  ters nor UTF-16 
2e9b0 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79  bytes.  .** ^Any
2e9c0 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
2e9d0 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
2e9e0 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
2e9f0 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
2ea00 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  in [SQLITE_MISUS
2ea10 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  E] being returne
2ea20 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  d..**.** ^The th
2ea30 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
2ea40 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
2ea50 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
2ea60 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
2ea70 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2ea80 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
2ea90 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74  ^If this paramet
2eaa0 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74  er is -1, then t
2eab0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
2eac0 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
2ead0 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
2eae0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
2eaf0 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
2eb00 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20  he limit.** set 
2eb10 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
2eb20 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
2eb30 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e  _FUNCTION_ARG]).
2eb40 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a    If the third.*
2eb50 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  * parameter is l
2eb60 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67  ess than -1 or g
2eb70 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20  reater than 127 
2eb80 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
2eb90 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
2eba0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
2ebb0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
2ebc0 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
2ebd0 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
2ebe0 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
2ebf0 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
2ec00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
2ec10 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
2ec20 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72  arameters.  Ever
2ec30 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
2ec40 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
2ec50 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  st be able to wo
2ec60 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38  rk.** with UTF-8
2ec70 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
2ec80 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
2ec90 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
2eca0 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
2ecb0 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
2ecc0 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
2ecd0 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e  an another.  ^An
2ece0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
2ecf0 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
2ed00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ed10 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
2ed20 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
2ed30 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  6() multiple.** 
2ed40 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
2ed50 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74  ame function but
2ed60 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
2ed70 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52  values of eTextR
2ed80 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c  ep..** ^When mul
2ed90 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
2eda0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2edb0 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
2edc0 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
2edd0 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
2ede0 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
2edf0 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
2ee00 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
2ee10 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74  version..** If t
2ee20 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73  here is only a s
2ee30 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ingle implementa
2ee40 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20  tion which does 
2ee50 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65  not care what te
2ee60 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69  xt.** encoding i
2ee70 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  s used, then the
2ee80 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
2ee90 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49   should be [SQLI
2eea0 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  TE_ANY]..**.** ^
2eeb0 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
2eec0 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
2eed0 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
2eee0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
2eef0 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
2ef00 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
2ef10 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
2ef20 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
2ef30 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
2ef40 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
2ef50 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
2ef60 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
2ef70 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
2ef80 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
2ef90 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
2efa0 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
2efb0 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
2efc0 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
2efd0 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2efe0 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
2eff0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
2f000 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
2f010 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
2f020 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
2f030 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
2f040 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
2f050 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
2f060 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
2f070 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
2f080 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2f090 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2f0a0 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2f0b0 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
2f0c0 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
2f0d0 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
2f0e0 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
2f0f0 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
2f100 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
2f110 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
2f120 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
2f130 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
2f140 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
2f150 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
2f160 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
2f170 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
2f180 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
2f190 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
2f1a0 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
2f1b0 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
2f1c0 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
2f1d0 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2f1e0 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
2f1f0 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
2f200 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
2f210 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
2f220 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
2f230 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
2f240 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
2f250 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2f260 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
2f270 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
2f280 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
2f290 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
2f2a0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2f2b0 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
2f2c0 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
2f2d0 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
2f2e0 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
2f2f0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
2f300 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
2f310 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
2f320 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
2f330 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
2f340 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
2f350 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
2f360 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
2f370 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2f380 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2f390 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
2f3a0 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
2f3b0 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
2f3c0 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
2f3d0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
2f3e0 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
2f3f0 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
2f400 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
2f410 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
2f420 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
2f430 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
2f440 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
2f450 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
2f460 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
2f470 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
2f480 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
2f490 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
2f4a0 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
2f4b0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
2f4c0 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
2f4d0 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
2f4e0 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
2f4f0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
2f500 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
2f510 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
2f520 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
2f530 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2f540 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
2f550 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
2f560 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2f570 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
2f580 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
2f590 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
2f5a0 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
2f5b0 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
2f5c0 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
2f5d0 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
2f5e0 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
2f5f0 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
2f600 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
2f610 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
2f620 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
2f630 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
2f640 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
2f650 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
2f660 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
2f670 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
2f680 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
2f690 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
2f6a0 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
2f6b0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
2f6c0 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
2f6d0 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
2f6e0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
2f6f0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
2f700 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2f710 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
2f720 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
2f730 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
2f740 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
2f750 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
2f760 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
2f770 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2f780 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
2f790 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
2f7a0 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
2f7b0 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
2f7c0 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
2f7d0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
2f7e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2f7f0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2f800 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
2f810 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
2f820 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
2f830 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
2f840 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
2f850 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
2f860 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
2f870 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2f880 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2f890 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
2f8a0 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
2f8b0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2f8c0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2f8d0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
2f8e0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
2f8f0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2f900 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2f910 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
2f920 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2f930 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
2f940 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2f950 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2f960 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2f970 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2f980 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f990 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2f9a0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2f9b0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2f9c0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2f9d0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2f9e0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2f9f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2fa00 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
2fa10 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
2fa20 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20  e_function_v2(. 
2fa30 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
2fa40 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
2fa50 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
2fa60 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
2fa70 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
2fa80 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
2fa90 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
2faa0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
2fab0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
2fac0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
2fad0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
2fae0 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
2faf0 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
2fb00 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
2fb10 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  ext*),.  void(*x
2fb20 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
2fb30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2fb40 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
2fb50 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
2fb60 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
2fb70 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
2fb80 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
2fb90 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
2fba0 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
2fbb0 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
2fbc0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
2fbd0 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
2fbe0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
2fbf0 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
2fc00 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2fc10 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
2fc20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
2fc30 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
2fc40 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
2fc50 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
2fc60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2fc70 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
2fc80 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
2fc90 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f  reate_function o
2fca0 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
2fcb0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
2fcc0 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
2fcd0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2fce0 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
2fcf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2fd00 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
2fd10 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
2fd20 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
2fd30 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
2fd40 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
2fd50 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
2fd60 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
2fd70 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
2fd80 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
2fd90 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
2fda0 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
2fdb0 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
2fdc0 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
2fdd0 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
2fde0 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
2fdf0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
2fe00 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72    To help encour
2fe10 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76  age people to av
2fe20 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  oid.** using the
2fe30 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65  se functions, we
2fe40 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74   are not going t
2fe50 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20  o tell you what 
2fe60 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e  they do..*/.#ifn
2fe70 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
2fe80 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54  DEPRECATED.SQLIT
2fe90 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
2fea0 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2feb0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2fec0 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
2fed0 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
2fee0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
2fef0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2ff00 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
2ff10 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  stmt*);.SQLITE_A
2ff20 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
2ff30 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2ff40 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
2ff50 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2ff60 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
2ff70 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
2ff80 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
2ff90 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
2ffa0 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
2ffb0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
2ffc0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
2ffd0 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
2ffe0 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
2fff0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
30000 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
30010 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
30020 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
30030 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
30040 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
30050 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
30060 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
30070 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
30080 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
30090 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a  ameter Values.**
300a0 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
300b0 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
300c0 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
300d0 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
300e0 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
300f0 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
30100 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
30110 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
30120 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
30130 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
30140 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
30150 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
30160 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
30170 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
30180 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
30190 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
301a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
301b0 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
301c0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
301d0 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
301e0 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
301f0 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
30200 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
30210 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
30220 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
30230 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
30240 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
30250 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
30260 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
30270 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30280 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
30290 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
302a0 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
302b0 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
302c0 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
302d0 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
302e0 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
302f0 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
30300 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
30310 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
30320 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
30330 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
30340 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
30350 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
30360 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
30370 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
30380 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
30390 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
303a0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
303b0 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
303c0 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
303d0 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
303e0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
303f0 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
30400 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
30410 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
30420 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
30430 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
30440 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
30450 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
30460 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
30470 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
30480 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
30490 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
304a0 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
304b0 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
304c0 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
304d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
304e0 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
304f0 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
30500 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
30510 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
30520 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
30530 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
30540 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
30550 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
30560 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
30570 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
30580 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
30590 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
305a0 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
305b0 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
305c0 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
305d0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
305e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
305f0 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
30600 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
30610 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
30620 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
30630 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
30640 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
30650 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
30660 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
30670 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
30680 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
30690 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
306a0 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
306b0 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
306c0 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
306d0 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
306e0 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
306f0 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
30700 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
30710 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
30720 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
30730 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
30740 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
30750 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
30760 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
30770 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
30780 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
30790 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
307a0 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
307b0 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
307c0 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
307d0 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
307e0 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
307f0 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
30800 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
30810 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
30820 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
30830 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
30840 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
30850 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
30860 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
30870 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
30880 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
30890 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
308a0 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
308b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
308c0 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
308d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
308e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
308f0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
30900 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
30910 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
30920 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
30930 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
30940 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
30950 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
30960 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  rs..*/.SQLITE_AP
30970 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
30980 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
30990 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
309a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
309b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
309c0 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
309d0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
309e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
309f0 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
30a00 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
30a10 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71  TE_API double sq
30a20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
30a30 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
30a40 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
30a50 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
30a60 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
30a70 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
30a80 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
30a90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
30aa0 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
30ab0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
30ac0 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
30ad0 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
30ae0 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
30af0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
30b00 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
30b10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
30b20 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
30b30 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
30b40 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
30b50 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
30b60 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
30b70 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
30b80 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
30b90 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
30ba0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
30bb0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
30bc0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
30bd0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
30be0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
30bf0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
30c00 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
30c10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
30c20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30c30 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
30c40 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
30c50 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
30c60 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
30c70 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
30c80 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
30c90 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
30ca0 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
30cb0 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
30cc0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
30cd0 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
30ce0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
30cf0 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
30d00 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
30d10 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
30d20 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
30d30 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
30d40 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
30d50 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
30d60 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
30d70 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
30d80 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
30d90 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
30da0 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
30db0 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
30dc0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
30dd0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
30de0 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
30df0 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
30e00 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
30e10 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
30e20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
30e30 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
30e40 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
30e50 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
30e60 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
30e70 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
30e80 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
30e90 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
30ea0 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
30eb0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
30ec0 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
30ed0 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
30ee0 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
30ef0 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
30f00 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
30f10 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
30f20 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
30f30 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
30f40 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
30f50 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
30f60 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
30f70 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
30f80 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
30f90 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
30fa0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
30fb0 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
30fc0 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
30fd0 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
30fe0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
30ff0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
31000 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
31010 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
31020 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c  ter if N is.** l
31030 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
31040 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
31050 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
31060 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
31070 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
31080 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
31090 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
310a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
310b0 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
310c0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
310d0 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
310e0 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
310f0 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
31100 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
31110 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
31120 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
31130 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
31140 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
31150 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
31160 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
31170 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
31180 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
31190 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a   allocation.)^.*
311a0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
311b0 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
311c0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
311d0 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
311e0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
311f0 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
31200 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
31210 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
31220 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
31230 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
31240 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
31250 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
31260 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
31270 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
31280 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
31290 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
312a0 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
312b0 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
312c0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
312d0 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
312e0 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
312f0 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
31300 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
31310 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
31320 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
31330 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
31340 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
31350 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
31360 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
31370 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31380 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
31390 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
313a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
313b0 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
313c0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
313d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73   ^The sqlite3_us
313e0 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
313f0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
31400 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
31410 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
31420 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
31430 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
31440 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
31450 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
31460 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
31470 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
31480 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
31490 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
314a0 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
314b0 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
314c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
314d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
314e0 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
314f0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
31500 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
31510 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
31520 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
31530 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
31540 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
31550 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
31560 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
31570 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
31580 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
31590 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
315a0 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
315b0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
315c0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ^The sqlite3_con
315d0 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
315e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
315f0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
31600 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
31610 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
31620 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
31630 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
31640 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
31650 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
31660 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
31670 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31680 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
31690 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
316a0 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
316b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
316c0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
316d0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
316e0 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
316f0 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
31700 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
31710 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
31720 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
31730 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a  uxiliary Data.**
31740 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
31750 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  g two functions 
31760 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73  may be used by s
31770 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
31780 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
31790 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
317a0 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
317b0 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
317c0 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
317d0 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
317e0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
317f0 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
31800 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
31810 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
31820 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
31830 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
31840 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
31850 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
31860 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20   This may.** be 
31870 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
31880 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75  e, to add a regu
31890 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
318a0 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a  atching scalar.*
318b0 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
318c0 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
318d0 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
318e0 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74  expression is st
318f0 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
31900 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
31910 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75  ith the SQL valu
31920 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
31930 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
31940 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20  on.** pattern.  
31950 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  The compiled reg
31960 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
31970 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
31980 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
31990 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
319a0 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f  same function so
319b0 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e   that the origin
319c0 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  al pattern strin
319d0 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65  g.** does not ne
319e0 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69  ed to be recompi
319f0 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f  led on each invo
31a00 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  cation..**.** ^T
31a10 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
31a20 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
31a30 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
31a40 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
31a50 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
31a60 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
31a70 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
31a80 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
31a90 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
31aa0 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
31ab0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31ac0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66  ed function. ^If
31ad0 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73   no metadata has
31ae0 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65   been ever.** be
31af0 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e  en set for the N
31b00 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  th argument of t
31b10 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20  he function, or 
31b20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  if the correspon
31b30 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ding.** function
31b40 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63   parameter has c
31b50 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65  hanged since the
31b60 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73   meta-data was s
31b70 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  et,.** then sqli
31b80 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
31b90 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
31ba0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
31bb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ^The sqlite3_set
31bc0 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
31bd0 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d  face saves the m
31be0 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74  etadata.** point
31bf0 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64  ed to by its 3rd
31c00 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
31c10 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  e metadata for t
31c20 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
31c30 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
31c40 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31c50 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71  unction.  Subseq
31c60 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
31c70 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
31c80 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74  data() might ret
31c90 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69  urn this data, i
31ca0 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20  f it has.** not 
31cb0 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a  been destroyed..
31cc0 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74  ** ^If it is not
31cd0 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
31ce0 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
31cf0 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63  structor.** func
31d00 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68  tion given by th
31d10 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
31d20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
31d30 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74  uxdata() on.** t
31d40 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e  he metadata when
31d50 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
31d60 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
31d70 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a  meter changes.**
31d80 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c   or when the SQL
31d90 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c   statement compl
31da0 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20  etes, whichever 
31db0 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a  comes first..**.
31dc0 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
31dd0 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65  e to call the de
31de0 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f  structor and dro
31df0 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e  p metadata on an
31e00 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
31e10 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61  f any function a
31e20 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68  t any time.  ^Th
31e30 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65  e only guarantee
31e40 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20   is that.** the 
31e50 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20  destructor will 
31e60 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65  be called before
31e70 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
31e80 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20   dropped..**.** 
31e90 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  ^(In practice, m
31ea0 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
31eb0 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
31ec0 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
31ed0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
31ee0 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
31ef0 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
31f00 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
31f10 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
31f20 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72  s and [parameter
31f30 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  s].)^.**.** Thes
31f40 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
31f50 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
31f60 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
31f70 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
31f80 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
31f90 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
31fa0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
31fb0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
31fc0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31fd0 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45  , int N);.SQLITE
31fe0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
31ff0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
32000 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
32010 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
32020 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
32030 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
32040 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
32050 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
32060 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
32070 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
32080 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
32090 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
320a0 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
320b0 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
320c0 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
320d0 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
320e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
320f0 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  lob()].  ^If the
32100 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
32110 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
32120 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
32130 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
32140 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
32150 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
32160 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
32170 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
32180 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
32190 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51  yed.  ^The.** SQ
321a0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
321b0 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
321c0 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
321d0 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
321e0 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
321f0 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
32200 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
32210 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
32220 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
32230 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
32240 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
32250 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
32260 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
32270 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
32280 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
32290 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53  ++ compilers.  S
322a0 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e  ee ticket #2191.
322b0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
322c0 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
322d0 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
322e0 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
322f0 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
32300 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
32310 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
32320 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
32330 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
32340 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
32350 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
32360 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
32370 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
32380 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a  QL Function.**.*
32390 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
323a0 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
323b0 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
323c0 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
323d0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
323e0 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
323f0 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
32400 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
32410 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
32420 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
32430 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
32440 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
32450 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
32460 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
32470 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
32480 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70  much like the [p
32490 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
324a0 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66  ] family of.** f
324b0 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
324c0 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
324d0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
324e0 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
324f0 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
32500 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72   to the [SQL par
32510 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74  ameter] document
32520 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
32530 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
32540 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
32550 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
32560 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
32570 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
32580 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
32590 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
325a0 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
325b0 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
325c0 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
325d0 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
325e0 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
325f0 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
32600 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
32610 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
32620 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
32630 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32640 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74  t_zeroblob() int
32650 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20  erfaces set the 
32660 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
32670 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
32680 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
32690 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61   be a BLOB conta
326a0 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a  ining all zero.*
326b0 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79  * bytes and N by
326c0 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65  tes in size, whe
326d0 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75  re N is the valu
326e0 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72  e of the 2nd par
326f0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
32700 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
32710 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72  t_double() inter
32720 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
32730 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
32740 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32750 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
32760 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  be a floating po
32770 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66  int value specif
32780 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e  ied.** by its 2n
32790 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
327a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
327b0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
327c0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
327d0 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
327e0 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
327f0 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
32800 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
32810 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
32820 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  ..** ^SQLite use
32830 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69  s the string poi
32840 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a  nted to by the.*
32850 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
32860 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  of sqlite3_resul
32870 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
32880 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
32890 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20  r16().** as the 
328a0 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
328b0 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69   message.  ^SQLi
328c0 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
328d0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
328e0 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
328f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32900 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
32910 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72  ^SQLite.** inter
32920 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67  prets the string
32930 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
32940 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61  sult_error16() a
32950 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  s UTF-16 in nati
32960 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72  ve.** byte order
32970 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  .  ^If the third
32980 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
32990 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
329a0 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
329b0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
329c0 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
329d0 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
329e0 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
329f0 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
32a00 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
32a10 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
32a20 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
32a30 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
32a40 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
32a50 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a  sult_error() or.
32a60 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
32a70 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
32a80 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e  on-negative then
32a90 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
32aa0 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73  at many.** bytes
32ab0 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
32ac0 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  ) from the 2nd p
32ad0 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
32ae0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
32af0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
32b00 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
32b10 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
32b20 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
32b30 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72  utines make a pr
32b40 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
32b50 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
32b60 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74  text before.** t
32b70 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e  hey return.  Hen
32b80 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ce, the calling 
32b90 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61  function can dea
32ba0 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f  llocate or.** mo
32bb0 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66  dify the text af
32bc0 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20  ter they return 
32bd0 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
32be0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
32bf0 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
32c00 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
32c10 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
32c20 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
32c30 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
32c40 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
32c50 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
32c60 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20  ^By default,.** 
32c70 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
32c80 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
32c90 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63   ^A subsequent c
32ca0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
32cb0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
32cc0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
32cd0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73  lt_error16() res
32ce0 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ets the error co
32cf0 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52  de to SQLITE_ERR
32d00 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  OR..**.** ^The s
32d10 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
32d20 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ror_toobig() int
32d30 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
32d40 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
32d50 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61  .** error indica
32d60 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
32d70 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
32d80 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73  o long to repres
32d90 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
32da0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32db0 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  rror_nomem() int
32dc0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
32dd0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
32de0 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61  .** error indica
32df0 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
32e00 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
32e10 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
32e20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
32e30 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
32e40 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
32e50 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
32e60 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
32e70 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
32e80 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
32e90 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
32ea0 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
32eb0 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
32ec0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32ed0 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
32ee0 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
32ef0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
32f00 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
32f10 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32f20 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
32f30 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
32f40 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
32f50 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
32f60 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
32f70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
32f80 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
32f90 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
32fa0 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
32fb0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
32fc0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
32fd0 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
32fe0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
32ff0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
33000 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33010 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
33020 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
33030 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
33040 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
33050 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
33060 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
33070 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
33080 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33090 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
330a0 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
330b0 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
330c0 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
330d0 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
330e0 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
330f0 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
33100 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
33110 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
33120 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51  ectively..** ^SQ
33130 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
33140 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
33150 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
33160 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
33170 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
33180 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33190 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
331a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
331b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
331c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
331d0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
331e0 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
331f0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
33200 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
33210 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
33220 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
33230 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
33240 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
33250 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
33260 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
33270 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
33280 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
33290 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
332a0 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
332b0 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
332c0 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
332d0 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
332e0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
332f0 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
33300 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
33310 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
33320 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20  ion result.  If 
33330 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
33340 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  r is non-negativ
33350 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75  e, then it.** mu
33360 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
33370 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73  ffset into the s
33380 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20  tring where the 
33390 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
333a0 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69  ould.** appear i
333b0 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  f the string whe
333c0 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65  re NUL terminate
333d0 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
333e0 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a  haracters occur.
333f0 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  ** in the string
33400 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65   at a byte offse
33410 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74  t that is less t
33420 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  han the value of
33430 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61   the 3rd.** para
33440 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
33450 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
33460 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d   will contain em
33470 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20  bedded NULs and 
33480 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66  the.** result of
33490 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65   expressions ope
334a0 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67  rating on string
334b0 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  s with embedded 
334c0 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
334d0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  d..** ^If the 4t
334e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
334f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
33500 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
33510 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
33520 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
33530 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
33540 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
33550 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
33560 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
33570 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
33580 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
33590 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
335a0 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
335b0 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
335c0 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
335d0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
335e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
335f0 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
33600 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
33610 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
33620 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
33630 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
33640 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
33650 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
33660 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
33670 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
33680 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
33690 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
336a0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
336b0 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
336c0 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
336d0 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
336e0 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
336f0 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
33700 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
33710 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
33720 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
33730 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
33740 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
33750 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
33760 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
33770 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
33780 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
33790 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
337a0 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
337b0 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
337c0 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
337d0 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
337e0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
337f0 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
33800 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33810 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
33820 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
33830 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
33840 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
33850 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
33860 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
33870 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
33880 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
33890 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
338a0 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
338b0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
338c0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
338d0 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
338e0 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
338f0 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
33900 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
33910 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
33920 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
33930 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
33940 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
33950 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
33960 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
33970 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
33980 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
33990 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
339a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
339b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
339c0 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
339d0 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
339e0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
339f0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
33a00 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
33a10 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
33a20 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
33a30 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
33a40 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
33a50 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
33a60 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
33a70 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
33a80 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
33a90 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
33aa0 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
33ab0 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
33ac0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33ad0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
33ae0 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
33af0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
33b00 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
33b10 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
33b20 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ned..*/.SQLITE_A
33b30 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
33b40 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
33b50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
33b60 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
33b70 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
33b80 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
33b90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33ba0 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
33bb0 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
33bc0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
33bd0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33be0 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
33bf0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
33c00 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  har*, int);.SQLI
33c10 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
33c20 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
33c30 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
33c40 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
33c50 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
33c60 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
33c70 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
33c80 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
33c90 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
33ca0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
33cb0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
33cc0 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
33cd0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
33ce0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
33cf0 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
33d00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33d10 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
33d20 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
33d30 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
33d40 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
33d50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
33d60 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
33d70 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
33d80 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
33d90 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f  _int64);.SQLITE_
33da0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
33db0 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c  _result_null(sql
33dc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
33dd0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
33de0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33df0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
33e00 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
33e10 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
33e20 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
33e30 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
33e40 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
33e50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33e60 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
33e70 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
33e80 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
33e90 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33ea0 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
33eb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
33ec0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
33ed0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
33ee0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
33ef0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
33f00 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
33f10 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
33f20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
33f30 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
33f40 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
33f50 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
33f60 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
33f70 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
33f80 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
33f90 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
33fa0 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
33fb0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
33fc0 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
33fd0 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
33fe0 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
33ff0 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ences.**.** ^The
34000 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64  se functions add
34010 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64  , remove, or mod
34020 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e  ify a [collation
34030 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  ] associated.** 
34040 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
34050 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
34060 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
34070 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
34080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
34090 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
340a0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
340b0 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
340c0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
340d0 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
340e0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
340f0 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
34100 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
34110 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
34120 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  er for sqlite3_c
34130 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
34140 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  6()..** ^Collati
34150 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f  on names that co
34160 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f  mpare equal acco
34170 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65  rding to [sqlite
34180 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72  3_strnicmp()] ar
34190 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
341a0 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e  to be the same n
341b0 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ame..**.** ^(The
341c0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
341d0 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20  (eTextRep) must 
341e0 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
341f0 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e  nstants:.** <ul>
34200 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
34210 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _UTF8],.** <li> 
34220 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
34230 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
34240 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c  E_UTF16BE],.** <
34250 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
34260 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  6], or.** <li> [
34270 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
34280 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29  GNED]..** </ul>)
34290 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52  ^.** ^The eTextR
342a0 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65  ep argument dete
342b0 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64  rmines the encod
342c0 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70  ing of strings p
342d0 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  assed.** to the 
342e0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
342f0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61  on callback, xCa
34300 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
34310 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61  [SQLITE_UTF16] a
34320 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  nd [SQLITE_UTF16
34330 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73  _ALIGNED] values
34340 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a   for eTextRep.**
34350 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74   force strings t
34360 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20  o be UTF16 with 
34370 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
34380 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  r..** ^The [SQLI
34390 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
343a0 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78  ] value for eTex
343b0 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69  tRep forces stri
343c0 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20  ngs to begin.** 
343d0 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20  on an even byte 
343e0 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e  address..**.** ^
343f0 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
34400 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e  ent, pArg, is an
34410 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
34420 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  a pointer that i
34430 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f  s passed.** thro
34440 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
34450 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
34460 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
34470 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
34480 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
34490 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61  rgument, xCallba
344a0 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ck, is a pointer
344b0 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
344c0 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e  g function..** ^
344d0 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69  Multiple collati
344e0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e  ng functions can
344f0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75   be registered u
34500 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  sing the same na
34510 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64  me but.** with d
34520 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
34530 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  p parameters and
34540 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
34550 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75   whichever.** fu
34560 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
34570 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
34580 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f   of data transfo
34590 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  rmation..** ^If 
345a0 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72  the xCallback ar
345b0 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74  gument is NULL t
345c0 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  hen the collatin
345d0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  g function is.**
345e0 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e   deleted.  ^When
345f0 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66   all collating f
34600 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20  unctions having 
34610 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  the same name ar
34620 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68  e deleted,.** th
34630 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  at collation is 
34640 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65  no longer usable
34650 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
34660 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
34670 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
34680 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20  ked with a copy 
34690 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20  of the pArg .** 
346a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
346b0 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74   pointer and wit
346c0 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e  h two strings in
346d0 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
346e0 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
346f0 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
34700 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74  ent.  The collat
34710 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
34720 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69  t return an.** i
34730 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e  nteger that is n
34740 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f  egative, zero, o
34750 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66  r positive.** if
34760 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
34770 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20  g is less than, 
34780 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
34790 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
347a0 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74  cond,.** respect
347b0 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74  ively.  A collat
347c0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
347d0 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  t always return 
347e0 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a  the same answer.
347f0 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d  ** given the sam
34800 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77  e inputs.  If tw
34810 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74  o or more collat
34820 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
34830 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20  e registered.** 
34840 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c  to the same coll
34850 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e  ation name (usin
34860 67 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78  g different eTex
34870 74 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65  tRep values) the
34880 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69  n all.** must gi
34890 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74  ve an equivalent
348a0 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76   answer when inv
348b0 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61  oked with equiva
348c0 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a  lent strings..**
348d0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
348e0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65  unction must obe
348f0 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  y the following 
34900 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61  properties for a
34910 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c  ll.** strings A,
34920 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a   B, and C:.**.**
34930 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66   <ol>.** <li> If
34940 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e   A==B then B==A.
34950 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
34960 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41   and B==C then A
34970 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==C..** <li> If 
34980 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74  A&lt;B THEN B&gt
34990 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  ;A..** <li> If A
349a0 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43  &lt;B and B&lt;C
349b0 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a   then A&lt;C..**
349c0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </ol>.**.** If 
349d0 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  a collating func
349e0 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f  tion fails any o
349f0 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73  f the above cons
34a00 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74  traints and that
34a10 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  .** collating fu
34a20 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73  nction is  regis
34a30 74 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20  tered and used, 
34a40 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
34a50 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69  r of SQLite.** i
34a60 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
34a70 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34a80 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
34a90 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65  _v2() works like
34aa0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
34ab0 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77  collation().** w
34ac0 69 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e  ith the addition
34ad0 20 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72   that the xDestr
34ae0 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  oy callback is i
34af0 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77  nvoked on pArg w
34b00 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61  hen.** the colla
34b10 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73  ting function is
34b20 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f   deleted..** ^Co
34b30 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
34b40 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68  s are deleted wh
34b50 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72  en they are over
34b60 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a  ridden by later.
34b70 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ** calls to the 
34b80 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69  collation creati
34b90 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  on functions or 
34ba0 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74  when the.** [dat
34bb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34bc0 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e  ] is closed usin
34bd0 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  g [sqlite3_close
34be0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ()]..**.** ^The 
34bf0 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
34c00 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20  k is <u>not</u> 
34c10 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a  called if the .*
34c20 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
34c30 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
34c40 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20  function fails. 
34c50 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
34c60 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  at invoke.** sql
34c70 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
34c80 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20  ation_v2() with 
34c90 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74  a non-NULL xDest
34ca0 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  roy argument sho
34cb0 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68  uld .** check th
34cc0 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e  e return code an
34cd0 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65  d dispose of the
34ce0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
34cf0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65  a pointer.** the
34d00 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74  mselves rather t
34d10 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51  han expecting SQ
34d20 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74  Lite to deal wit
34d30 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a  h it for them..*
34d40 2a 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72  * This is differ
34d50 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f  ent from every o
34d60 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
34d70 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f  rface.  The inco
34d80 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73  nsistency .** is
34d90 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74   unfortunate but
34da0 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
34db0 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ed without break
34dc0 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a  ing backwards .*
34dd0 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  * compatibility.
34de0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
34df0 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61    [sqlite3_colla
34e00 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61  tion_needed()] a
34e10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  nd [sqlite3_coll
34e20 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29  ation_needed16()
34e30 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
34e40 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65   int sqlite3_cre
34e50 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20  ate_collation(. 
34e60 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
34e70 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
34e80 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70   .  int eTextRep
34e90 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c  , .  void *pArg,
34ea0 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65  .  int(*xCompare
34eb0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
34ec0 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  t void*,int,cons
34ed0 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49  t void*).);.SQLI
34ee0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
34ef0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
34f00 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
34f10 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
34f20 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
34f30 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
34f40 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
34f50 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
34f60 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
34f70 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
34f80 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
34f90 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 53  roy)(void*).);.S
34fa0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
34fb0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
34fc0 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  lation16(.  sqli
34fd0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76  te3*, .  const v
34fe0 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e  oid *zName,.  in
34ff0 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
35000 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
35010 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
35020 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
35030 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
35040 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
35050 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e  I3REF: Collation
35060 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b   Needed Callback
35070 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69  s.**.** ^To avoi
35080 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69  d having to regi
35090 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  ster all collati
350a0 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62 65 66  on sequences bef
350b0 6f 72 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a  ore a database.*
350c0 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61  * can be used, a
350d0 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b   single callback
350e0 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
350f0 20 72 65 67 69 73 74 65 72 65 64 20 77 69 74 68   registered with
35100 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
35110 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
35120 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   be invoked when
35130 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65  ever an undefine
35140 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73  d collation.** s
35150 65 71 75 65 6e 63 65 20 69 73 20 72 65 71 75 69  equence is requi
35160 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  red..**.** ^If t
35170 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
35180 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
35190 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  the sqlite3_coll
351a0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41  ation_needed() A
351b0 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  PI,.** then it i
351c0 73 20 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d  s passed the nam
351d0 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20  es of undefined 
351e0 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e  collation sequen
351f0 63 65 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a  ces as strings.*
35200 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46  * encoded in UTF
35210 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  -8. ^If sqlite3_
35220 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
35230 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a  16() is used,.**
35240 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70   the names are p
35250 61 73 73 65 64 20 61 73 20 55 54 46 2d 31 36 20  assed as UTF-16 
35260 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76  in machine nativ
35270 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
35280 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68   ^A call to eith
35290 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c  er function repl
352a0 61 63 65 73 20 74 68 65 20 65 78 69 73 74 69 6e  aces the existin
352b0 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64  g collation-need
352c0 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  ed callback..**.
352d0 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61  ** ^(When the ca
352e0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
352f0 64 2c 20 74 68 65 20 66 69 72 73 74 20 61 72 67  d, the first arg
35300 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69 73 20  ument passed is 
35310 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65  a copy.** of the
35320 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
35330 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c   to sqlite3_coll
35340 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f  ation_needed() o
35350 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r.** sqlite3_col
35360 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28  lation_needed16(
35370 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ).  The second a
35380 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64  rgument is the d
35390 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
353a0 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72  ction.  The thir
353b0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e  d argument is on
353c0 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46  e of [SQLITE_UTF
353d0 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  8], [SQLITE_UTF1
353e0 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  6BE],.** or [SQL
353f0 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e  ITE_UTF16LE], in
35400 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73  dicating the mos
35410 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d  t desirable form
35420 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f   of the collatio
35430 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75  n.** sequence fu
35440 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e  nction required.
35450 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72    The fourth par
35460 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
35470 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71  me of the.** req
35480 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  uired collation 
35490 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a  sequence.)^.**.*
354a0 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66  * The callback f
354b0 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72  unction should r
354c0 65 67 69 73 74 65 72 20 74 68 65 20 64 65 73 69  egister the desi
354d0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73  red collation us
354e0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
354f0 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
35500 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72  ()], [sqlite3_cr
35510 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
35520 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
35530 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35540 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53  tion_v2()]..*/.S
35550 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
35560 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
35570 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69 74 65  needed(.  sqlite
35580 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20  3*, .  void*, . 
35590 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73   void(*)(void*,s
355a0 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78  qlite3*,int eTex
355b0 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a  tRep,const char*
355c0 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
355d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c  int sqlite3_coll
355e0 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a  ation_needed16(.
355f0 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
35600 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28  oid*,.  void(*)(
35610 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69  void*,sqlite3*,i
35620 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73  nt eTextRep,cons
35630 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66  t void*).);..#if
35640 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43  def SQLITE_HAS_C
35650 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69  ODEC./*.** Speci
35660 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61  fy the key for a
35670 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61  n encrypted data
35680 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74  base.  This rout
35690 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a  ine should be.**
356a0 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66   called right af
356b0 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ter sqlite3_open
356c0 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ()..**.** The co
356d0 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  de to implement 
356e0 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20  this API is not 
356f0 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65  available in the
35700 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a   public release.
35710 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f  ** of SQLite..*/
35720 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
35730 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20 20 73  sqlite3_key(.  s
35740 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
35750 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
35760 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
35770 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
35780 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
35790 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
357a0 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a  he key */.);../*
357b0 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65 20 6b  .** Change the k
357c0 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61  ey on an open da
357d0 74 61 62 61 73 65 2e 20 20 49 66 20 74 68 65 20  tabase.  If the 
357e0 63 75 72 72 65 6e 74 20 64 61 74 61 62 61 73 65  current database
357f0 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79   is not.** encry
35800 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75 74 69  pted, this routi
35810 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70 74 20  ne will encrypt 
35820 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d 30 20  it.  If pNew==0 
35830 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a  or nNew==0, the.
35840 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73 20 64  ** database is d
35850 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ecrypted..**.** 
35860 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c  The code to impl
35870 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49 20 69  ement this API i
35880 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c 65 20  s not available 
35890 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20 72 65  in the public re
358a0 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  lease.** of SQLi
358b0 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te..*/.SQLITE_AP
358c0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  I int sqlite3_re
358d0 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  key(.  sqlite3 *
358e0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
358f0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
35900 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
35910 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
35920 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20  *pKey, int nKey 
35930 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b      /* The new k
35940 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ey */.);../*.** 
35950 53 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69  Specify the acti
35960 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61  vation key for a
35970 20 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20   SEE database.  
35980 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76  Unless .** activ
35990 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68  ated, none of th
359a0 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77  e SEE routines w
359b0 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c  ill work..*/.SQL
359c0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
359d0 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65  ite3_activate_se
359e0 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  e(.  const char 
359f0 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
35a00 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
35a10 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
35a20 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51  endif..#ifdef SQ
35a30 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f  LITE_ENABLE_CERO
35a40 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  D./*.** Specify 
35a50 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
35a60 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64  ey for a CEROD d
35a70 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73  atabase.  Unless
35a80 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20   .** activated, 
35a90 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f  none of the CERO
35aa0 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20  D routines will 
35ab0 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  work..*/.SQLITE_
35ac0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
35ad0 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28  _activate_cerod(
35ae0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
35af0 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
35b00 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
35b10 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
35b20 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
35b30 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65  REF: Suspend Exe
35b40 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f  cution For A Sho
35b50 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68  rt Time.**.** Th
35b60 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28  e sqlite3_sleep(
35b70 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  ) function cause
35b80 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74 68  s the current th
35b90 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20  read to suspend 
35ba0 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72  execution.** for
35bb0 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62   at least a numb
35bc0 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  er of millisecon
35bd0 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  ds specified in 
35be0 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  its parameter..*
35bf0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72  *.** If the oper
35c00 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65  ating system doe
35c10 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c  s not support sl
35c20 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69 74  eep requests wit
35c30 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  h.** millisecond
35c40 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e   time resolution
35c50 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20  , then the time 
35c60 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
35c70 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61  up to.** the nea
35c80 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65  rest second. The
35c90 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
35ca0 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
35cb0 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71   actually.** req
35cc0 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20  uested from the 
35cd0 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
35ce0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
35cf0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c  .** ^SQLite impl
35d00 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65  ements this inte
35d10 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67  rface by calling
35d20 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a   the xSleep().**
35d30 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
35d40 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
35d50 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66  vfs] object.  If
35d60 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   the xSleep() me
35d70 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64  thod.** of the d
35d80 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f  efault VFS is no
35d90 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f  t implemented co
35da0 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20  rrectly, or not 
35db0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a  implemented at.*
35dc0 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20  * all, then the 
35dd0 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69  behavior of sqli
35de0 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20  te3_sleep() may 
35df0 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65  deviate from the
35e00 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20   description.** 
35e10 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
35e20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 53  paragraphs..*/.S
35e30 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
35e40 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29  lite3_sleep(int)
35e50 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35e60 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46  F: Name Of The F
35e70 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65  older Holding Te
35e80 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a  mporary Files.**
35e90 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c  .** ^(If this gl
35ea0 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73  obal variable is
35eb0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
35ec0 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63 68  o a string which
35ed0 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20   is.** the name 
35ee0 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b  of a folder (a.k
35ef0 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20  .a. directory), 
35f00 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61  then all tempora
35f10 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61  ry files.** crea
35f20 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77 68  ted by SQLite wh
35f30 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
35f40 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  -in [sqlite3_vfs
35f50 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20   | VFS].** will 
35f60 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61  be placed in tha
35f70 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20  t directory.)^  
35f80 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62 6c  ^If this variabl
35f90 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  e.** is a NULL p
35fa0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
35fb0 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73  ite performs a s
35fc0 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70  earch for an app
35fd0 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70  ropriate.** temp
35fe0 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65 63  orary file direc
35ff0 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69  tory..**.** It i
36000 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65  s not safe to re
36010 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ad or modify thi
36020 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f  s variable in mo
36030 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74  re than one.** t
36040 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e  hread at a time.
36050 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65    It is not safe
36060 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
36070 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
36080 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61  .** if a [databa
36090 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
360a0 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20  s being used at 
360b0 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e  the same time in
360c0 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74   a separate.** t
360d0 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20  hread..** It is 
360e0 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68  intended that th
360f0 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73  is variable be s
36100 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61  et once.** as pa
36110 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e  rt of process in
36120 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
36130 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69   before any SQLi
36140 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  te interface.** 
36150 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65  routines have be
36160 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68  en called and th
36170 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
36180 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65   remain unchange
36190 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e  d.** thereafter.
361a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d  .**.** ^The [tem
361b0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
361c0 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f  y pragma] may mo
361d0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
361e0 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20  le and cause.** 
361f0 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  it to point to m
36200 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
36210 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
36220 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d  loc].  ^Furtherm
36230 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d  ore,.** the [tem
36240 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
36250 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73  y pragma] always
36260 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e   assumes that an
36270 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74  y string.** that
36280 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70   this variable p
36290 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64  oints to is held
362a0 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   in memory obtai
362b0 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
362c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e  lite3_malloc] an
362d0 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79  d the pragma may
362e0 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65   attempt to free
362f0 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   that memory.** 
36300 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
36310 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20  ree]..** Hence, 
36320 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  if this variable
36330 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72   is modified dir
36340 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74  ectly, either it
36350 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61   should be.** ma
36360 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20  de NULL or made 
36370 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f  to point to memo
36380 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
36390 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
363a0 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65  ].** or else the
363b0 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d   use of the [tem
363c0 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
363d0 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64  y pragma] should
363e0 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a   be avoided..**.
363f0 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69  ** <b>Note to Wi
36400 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73  ndows Runtime us
36410 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65  ers:</b>  The te
36420 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72  mporary director
36430 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a  y must be set.**
36440 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
36450 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d  g [sqlite3_open]
36460 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
36470 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73  n_v2].  Otherwis
36480 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65  e, various.** fe
36490 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71 75  atures that requ
364a0 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  ire the use of t
364b0 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d  emporary files m
364c0 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69  ay fail.  Here i
364d0 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20  s an.** example 
364e0 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69  of how to do thi
364f0 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68  s using C++ with
36500 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e   the Windows Run
36510 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  time:.**.** <blo
36520 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
36530 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d   LPCWSTR zPath =
36540 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67   Windows::Storag
36550 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61  e::ApplicationDa
36560 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a  ta::Current->.**
36570 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70   &nbsp;     Temp
36580 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74  oraryFolder->Pat
36590 68 2d 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68  h->Data();.** ch
365a0 61 72 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b  ar zPathBuf&#91;
365b0 4d 41 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33  MAX_PATH + 1&#93
365c0 3b 3b 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61  ;;.** memset(zPa
365d0 74 68 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66  thBuf, 0, sizeof
365e0 28 7a 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20  (zPathBuf));.** 
365f0 57 69 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42  WideCharToMultiB
36600 79 74 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20  yte(CP_UTF8, 0, 
36610 7a 50 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68  zPath, -1, zPath
36620 42 75 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74  Buf, sizeof(zPat
36630 68 42 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b  hBuf),.** &nbsp;
36640 20 20 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29       NULL, NULL)
36650 3b 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d  ;.** sqlite3_tem
36660 70 5f 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71  p_directory = sq
36670 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25  lite3_mprintf("%
36680 73 22 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a  s", zPathBuf);.*
36690 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
366a0 75 6f 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  uote>.*/.SQLITE_
366b0 41 50 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52  API SQLITE_EXTER
366c0 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  N char *sqlite3_
366d0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a  temp_directory;.
366e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
366f0 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
36700 64 65 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61  der Holding Data
36710 62 61 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a  base Files.**.**
36720 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61   ^(If this globa
36730 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61  l variable is ma
36740 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  de to point to a
36750 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
36760 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  .** the name of 
36770 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e  a folder (a.k.a.
36780 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65   directory), the
36790 6e 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66  n all database f
367a0 69 6c 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65  iles.** specifie
367b0 64 20 77 69 74 68 20 61 20 72 65 6c 61 74 69 76  d with a relativ
367c0 65 20 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63  e pathname and c
367d0 72 65 61 74 65 64 20 6f 72 20 61 63 63 65 73 73  reated or access
367e0 65 64 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20  ed by.** SQLite 
367f0 77 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69  when using a bui
36800 6c 74 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73  lt-in windows [s
36810 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53  qlite3_vfs | VFS
36820 5d 20 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65  ] will be assume
36830 64 0a 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74  d.** to be relat
36840 69 76 65 20 74 6f 20 74 68 61 74 20 64 69 72 65  ive to that dire
36850 63 74 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69  ctory.)^ ^If thi
36860 73 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  s variable is a 
36870 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c  NULL.** pointer,
36880 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
36890 75 6d 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61  umes that all da
368a0 74 61 62 61 73 65 20 66 69 6c 65 73 20 73 70 65  tabase files spe
368b0 63 69 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61  cified.** with a
368c0 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61   relative pathna
368d0 6d 65 20 61 72 65 20 72 65 6c 61 74 69 76 65 20  me are relative 
368e0 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  to the current d
368f0 69 72 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20  irectory.** for 
36900 74 68 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e  the process.  On
36910 6c 79 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  ly the windows V
36920 46 53 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20  FS makes use of 
36930 74 68 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76  this global.** v
36940 61 72 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69  ariable; it is i
36950 67 6e 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e  gnored by the un
36960 69 78 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68  ix VFS..**.** Ch
36970 61 6e 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65  anging the value
36980 20 6f 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   of this variabl
36990 65 20 77 68 69 6c 65 20 61 20 64 61 74 61 62 61  e while a databa
369a0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
369b0 0a 2a 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73  .** open can res
369c0 75 6c 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74  ult in a corrupt
369d0 20 64 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a   database..**.**
369e0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
369f0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
36a00 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  y this variable 
36a10 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  in more than one
36a20 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20  .** thread at a 
36a30 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74  time.  It is not
36a40 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72   safe to read or
36a50 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
36a60 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64  iable.** if a [d
36a70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36a80 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65  on] is being use
36a90 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  d at the same ti
36aa0 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65  me in a separate
36ab0 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49  .** thread..** I
36ac0 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68  t is intended th
36ad0 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
36ae0 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20   be set once.** 
36af0 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65  as part of proce
36b00 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ss initializatio
36b10 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79  n and before any
36b20 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
36b30 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61  e.** routines ha
36b40 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61  ve been called a
36b50 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72  nd that this var
36b60 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63  iable remain unc
36b70 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61  hanged.** therea
36b80 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  fter..**.** ^The
36b90 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72   [data_store_dir
36ba0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d  ectory pragma] m
36bb0 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  ay modify this v
36bc0 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73  ariable and caus
36bd0 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74  e.** it to point
36be0 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69   to memory obtai
36bf0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
36c00 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72  3_malloc].  ^Fur
36c10 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65  thermore,.** the
36c20 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72   [data_store_dir
36c30 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61  ectory pragma] a
36c40 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68  lways assumes th
36c50 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a  at any string.**
36c60 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
36c70 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73  ble points to is
36c80 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20   held in memory 
36c90 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
36ca0 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
36cb0 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d  c] and the pragm
36cc0 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f  a may attempt to
36cd0 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72   free that memor
36ce0 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  y.** using [sqli
36cf0 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65  te3_free]..** He
36d00 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72  nce, if this var
36d10 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65  iable is modifie
36d20 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68  d directly, eith
36d30 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a  er it should be.
36d40 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20  ** made NULL or 
36d50 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
36d60 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
36d70 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
36d80 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73  alloc].** or els
36d90 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65  e the use of the
36da0 20 5b 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72   [data_store_dir
36db0 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73  ectory pragma] s
36dc0 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64  hould be avoided
36dd0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
36de0 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68  SQLITE_EXTERN ch
36df0 61 72 20 2a 73 71 6c 69 74 65 33 5f 64 61 74 61  ar *sqlite3_data
36e00 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a  _directory;../*.
36e10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73  ** CAPI3REF: Tes
36e20 74 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69  t For Auto-Commi
36e30 74 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52  t Mode.** KEYWOR
36e40 44 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20  DS: {autocommit 
36e50 6d 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mode}.**.** ^The
36e60 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74   sqlite3_get_aut
36e70 6f 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66  ocommit() interf
36e80 61 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ace returns non-
36e90 7a 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20  zero or.** zero 
36ea0 69 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74  if the given dat
36eb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36ec0 20 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e   is or is not in
36ed0 20 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65   autocommit mode
36ee0 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ,.** respectivel
36ef0 79 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20  y.  ^Autocommit 
36f00 6d 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65  mode is on by de
36f10 66 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63  fault..** ^Autoc
36f20 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69  ommit mode is di
36f30 73 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47  sabled by a [BEG
36f40 49 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  IN] statement..*
36f50 2a 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  * ^Autocommit mo
36f60 64 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64  de is re-enabled
36f70 20 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f   by a [COMMIT] o
36f80 72 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a  r [ROLLBACK]..**
36f90 0a 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b  .** If certain k
36fa0 69 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f  inds of errors o
36fb0 63 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d  ccur on a statem
36fc0 65 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c  ent within a mul
36fd0 74 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ti-statement.** 
36fe0 74 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72  transaction (err
36ff0 6f 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53  ors including [S
37000 51 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51  QLITE_FULL], [SQ
37010 4c 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20  LITE_IOERR],.** 
37020 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20  [SQLITE_NOMEM], 
37030 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61  [SQLITE_BUSY], a
37040 6e 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  nd [SQLITE_INTER
37050 52 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a  RUPT]) then the.
37060 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d  ** transaction m
37070 69 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62  ight be rolled b
37080 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ack automaticall
37090 79 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79  y.  The only way
370a0 20 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20   to.** find out 
370b0 77 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61  whether SQLite a
370c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c  utomatically rol
370d0 6c 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61  led back the tra
370e0 6e 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a  nsaction after.*
370f0 2a 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f  * an error is to
37100 20 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69   use this functi
37110 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f  on..**.** If ano
37120 74 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e  ther thread chan
37130 67 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d  ges the autocomm
37140 69 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65  it status of the
37150 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
37160 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
37170 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75  is routine is ru
37180 6e 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nning, then the 
37190 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20  return value.** 
371a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  is undefined..*/
371b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
371c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
371d0 63 6f 6d 6d 69 74 28 73 71 6c 69 74 65 33 2a 29  commit(sqlite3*)
371e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
371f0 46 3a 20 46 69 6e 64 20 54 68 65 20 44 61 74 61  F: Find The Data
37200 62 61 73 65 20 48 61 6e 64 6c 65 20 4f 66 20 41  base Handle Of A
37210 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
37220 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ent.**.** ^The s
37230 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
37240 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
37250 6e 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ns the [database
37260 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e   connection] han
37270 64 6c 65 0a 2a 2a 20 74 6f 20 77 68 69 63 68 20  dle.** to which 
37280 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
37290 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e 67 73 2e 20  ement] belongs. 
372a0 20 5e 54 68 65 20 5b 64 61 74 61 62 61 73 65 20   ^The [database 
372b0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72  connection].** r
372c0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
372d0 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 73 20  e3_db_handle is 
372e0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
372f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
37300 2a 20 74 68 61 74 20 77 61 73 20 74 68 65 20 66  * that was the f
37310 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
37320 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
37330 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 63  _prepare_v2()] c
37340 61 6c 6c 20 28 6f 72 20 69 74 73 20 76 61 72 69  all (or its vari
37350 61 6e 74 73 29 20 74 68 61 74 20 77 61 73 20 75  ants) that was u
37360 73 65 64 20 74 6f 0a 2a 2a 20 63 72 65 61 74 65  sed to.** create
37370 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
37380 6e 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63  n the first plac
37390 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
373a0 20 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65   sqlite3 *sqlite
373b0 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  3_db_handle(sqli
373c0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
373d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
373e0 75 72 6e 20 54 68 65 20 46 69 6c 65 6e 61 6d 65  urn The Filename
373f0 20 46 6f 72 20 41 20 44 61 74 61 62 61 73 65 20   For A Database 
37400 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  Connection.**.**
37410 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62   ^The sqlite3_db
37420 5f 66 69 6c 65 6e 61 6d 65 28 44 2c 4e 29 20 69  _filename(D,N) i
37430 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
37440 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
37450 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 61 73 73 6f  filename.** asso
37460 63 69 61 74 65 64 20 77 69 74 68 20 64 61 74 61  ciated with data
37470 62 61 73 65 20 4e 20 6f 66 20 63 6f 6e 6e 65 63  base N of connec
37480 74 69 6f 6e 20 44 2e 20 20 5e 54 68 65 20 6d 61  tion D.  ^The ma
37490 69 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  in database file
374a0 0a 2a 2a 20 68 61 73 20 74 68 65 20 6e 61 6d 65  .** has the name
374b0 20 22 6d 61 69 6e 22 2e 20 20 49 66 20 74 68 65   "main".  If the
374c0 72 65 20 69 73 20 6e 6f 20 61 74 74 61 63 68 65  re is no attache
374d0 64 20 64 61 74 61 62 61 73 65 20 4e 20 6f 6e 20  d database N on 
374e0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
374f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 6f 72  connection D, or
37500 20 69 66 20 64 61 74 61 62 61 73 65 20 4e 20 69   if database N i
37510 73 20 61 20 74 65 6d 70 6f 72 61 72 79 20 6f 72  s a temporary or
37520 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62   in-memory datab
37530 61 73 65 2c 20 74 68 65 6e 0a 2a 2a 20 61 20 4e  ase, then.** a N
37540 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
37550 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
37560 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 72 65 74  The filename ret
37570 75 72 6e 65 64 20 62 79 20 74 68 69 73 20 66 75  urned by this fu
37580 6e 63 74 69 6f 6e 20 69 73 20 74 68 65 20 6f 75  nction is the ou
37590 74 70 75 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78  tput of the.** x
375a0 46 75 6c 6c 50 61 74 68 6e 61 6d 65 20 6d 65 74  FullPathname met
375b0 68 6f 64 20 6f 66 20 74 68 65 20 5b 56 46 53 5d  hod of the [VFS]
375c0 2e 20 20 5e 49 6e 20 6f 74 68 65 72 20 77 6f 72  .  ^In other wor
375d0 64 73 2c 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ds, the filename
375e0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 61 6e 20 61  .** will be an a
375f0 62 73 6f 6c 75 74 65 20 70 61 74 68 6e 61 6d 65  bsolute pathname
37600 2c 20 65 76 65 6e 20 69 66 20 74 68 65 20 66 69  , even if the fi
37610 6c 65 6e 61 6d 65 20 75 73 65 64 0a 2a 2a 20 74  lename used.** t
37620 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62  o open the datab
37630 61 73 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 77  ase originally w
37640 61 73 20 61 20 55 52 49 20 6f 72 20 72 65 6c 61  as a URI or rela
37650 74 69 76 65 20 70 61 74 68 6e 61 6d 65 2e 0a 2a  tive pathname..*
37660 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
37670 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
37680 5f 64 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c  _db_filename(sql
37690 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20  ite3 *db, const 
376a0 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a  char *zDbName);.
376b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
376c0 20 44 65 74 65 72 6d 69 6e 65 20 69 66 20 61 20   Determine if a 
376d0 64 61 74 61 62 61 73 65 20 69 73 20 72 65 61 64  database is read
376e0 2d 6f 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  -only.**.** ^The
376f0 20 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64   sqlite3_db_read
37700 6f 6e 6c 79 28 44 2c 4e 29 20 69 6e 74 65 72 66  only(D,N) interf
37710 61 63 65 20 72 65 74 75 72 6e 73 20 31 20 69 66  ace returns 1 if
37720 20 74 68 65 20 64 61 74 61 62 61 73 65 20 4e 0a   the database N.
37730 2a 2a 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e  ** of connection
37740 20 44 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c   D is read-only,
37750 20 30 20 69 66 20 69 74 20 69 73 20 72 65 61 64   0 if it is read
37760 2f 77 72 69 74 65 2c 20 6f 72 20 2d 31 20 69 66  /write, or -1 if
37770 20 4e 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65   N is not.** the
37780 20 6e 61 6d 65 20 6f 66 20 61 20 64 61 74 61 62   name of a datab
37790 61 73 65 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f  ase on connectio
377a0 6e 20 44 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  n D..*/.SQLITE_A
377b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64  PI int sqlite3_d
377c0 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74  b_readonly(sqlit
377d0 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68  e3 *db, const ch
377e0 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f  ar *zDbName);../
377f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
37800 69 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65  ind the next pre
37810 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a  pared statement.
37820 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
37830 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
37840 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e  pointer to the n
37850 65 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74  ext [prepared st
37860 61 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a  atement] after.*
37870 2a 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74  * pStmt associat
37880 65 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74  ed with the [dat
37890 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
378a0 5d 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d  ] pDb.  ^If pStm
378b0 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65  t is NULL.** the
378c0 6e 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  n this interface
378d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
378e0 65 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  er to the first 
378f0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
37900 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  nt.** associated
37910 20 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61   with the databa
37920 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44  se connection pD
37930 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61  b.  ^If no prepa
37940 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
37950 20 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63   satisfies the c
37960 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69  onditions of thi
37970 73 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65  s routine, it re
37980 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  turns NULL..**.*
37990 2a 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20  * The [database 
379a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e  connection] poin
379b0 74 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20  ter D in a call 
379c0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e  to.** [sqlite3_n
379d0 65 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d  ext_stmt(D,S)] m
379e0 75 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20  ust refer to an 
379f0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a  open database.**
37a00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20   connection and 
37a10 69 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75  in particular mu
37a20 73 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c  st not be a NULL
37a30 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 53 51 4c   pointer..*/.SQL
37a40 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
37a50 73 74 6d 74 20 2a 73 71 6c 69 74 65 33 5f 6e 65  stmt *sqlite3_ne
37a60 78 74 5f 73 74 6d 74 28 73 71 6c 69 74 65 33 20  xt_stmt(sqlite3 
37a70 2a 70 44 62 2c 20 73 71 6c 69 74 65 33 5f 73 74  *pDb, sqlite3_st
37a80 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
37a90 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
37aa0 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62 61 63 6b  mit And Rollback
37ab0 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 20 43 61   Notification Ca
37ac0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
37ad0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69  he sqlite3_commi
37ae0 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  t_hook() interfa
37af0 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
37b00 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
37b10 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
37b20 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
37b30 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 43 4f 4d  nsaction is [COM
37b40 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74 65 64 5d  MIT | committed]
37b50 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61  ..** ^Any callba
37b60 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76  ck set by a prev
37b70 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ious call to sql
37b80 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
37b90 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65 20 73 61  ().** for the sa
37ba0 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
37bb0 65 63 74 69 6f 6e 20 69 73 20 6f 76 65 72 72 69  ection is overri
37bc0 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  dden..** ^The sq
37bd0 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
37be0 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20  ook() interface 
37bf0 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
37c00 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  back.** function
37c10 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
37c20 68 65 6e 65 76 65 72 20 61 20 74 72 61 6e 73 61  henever a transa
37c30 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c 4c 42 41  ction is [ROLLBA
37c40 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62 61 63 6b  CK | rolled back
37c50 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62  ]..** ^Any callb
37c60 61 63 6b 20 73 65 74 20 62 79 20 61 20 70 72 65  ack set by a pre
37c70 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 73 71  vious call to sq
37c80 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68  lite3_rollback_h
37c90 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
37ca0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
37cb0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
37cc0 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65  rridden..** ^The
37cd0 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 69   pArg argument i
37ce0 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
37cf0 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
37d00 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c  ..** ^If the cal
37d10 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f 6d 6d 69  lback on a commi
37d20 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69 6f 6e 20  t hook function 
37d30 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
37d40 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ,.** then the co
37d50 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65 72 74 65  mmit is converte
37d60 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c 62 61 63  d into a rollbac
37d70 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  k..**.** ^The sq
37d80 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f  lite3_commit_hoo
37d90 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20 73 71 6c  k(D,C,P) and sql
37da0 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f  ite3_rollback_ho
37db0 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e 63 74 69  ok(D,C,P) functi
37dc0 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e 20 74 68  ons.** return th
37dd0 65 20 50 20 61 72 67 75 6d 65 6e 74 20 66 72 6f  e P argument fro
37de0 6d 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  m the previous c
37df0 61 6c 6c 20 6f 66 20 74 68 65 20 73 61 6d 65 20  all of the same 
37e00 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 6e 20 74  function.** on t
37e10 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
37e20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
37e30 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20   or NULL for.** 
37e40 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 66  the first call f
37e50 6f 72 20 65 61 63 68 20 66 75 6e 63 74 69 6f 6e  or each function
37e60 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   on D..**.** The
37e70 20 63 6f 6d 6d 69 74 20 61 6e 64 20 72 6f 6c 6c   commit and roll
37e80 62 61 63 6b 20 68 6f 6f 6b 20 63 61 6c 6c 62 61  back hook callba
37e90 63 6b 73 20 61 72 65 20 6e 6f 74 20 72 65 65 6e  cks are not reen
37ea0 74 72 61 6e 74 2e 0a 2a 2a 20 54 68 65 20 63 61  trant..** The ca
37eb0 6c 6c 62 61 63 6b 20 69 6d 70 6c 65 6d 65 6e 74  llback implement
37ec0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 64  ation must not d
37ed0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
37ee0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
37ef0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
37f00 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
37f10 6b 65 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ked the callback
37f20 2e 20 20 41 6e 79 20 61 63 74 69 6f 6e 73 0a 2a  .  Any actions.*
37f30 2a 20 74 6f 20 6d 6f 64 69 66 79 20 74 68 65 20  * to modify the 
37f40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
37f50 69 6f 6e 20 6d 75 73 74 20 62 65 20 64 65 66 65  ion must be defe
37f60 72 72 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  rred until after
37f70 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 69   the.** completi
37f80 6f 6e 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  on of the [sqlit
37f90 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
37fa0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
37fb0 68 65 20 63 6f 6d 6d 69 74 0a 2a 2a 20 6f 72 20  he commit.** or 
37fc0 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 6e  rollback hook in
37fd0 20 74 68 65 20 66 69 72 73 74 20 70 6c 61 63 65   the first place
37fe0 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 72  ..** Note that r
37ff0 75 6e 6e 69 6e 67 20 61 6e 79 20 6f 74 68 65 72  unning any other
38000 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2c   SQL statements,
38010 20 69 6e 63 6c 75 64 69 6e 67 20 53 45 4c 45 43   including SELEC
38020 54 20 73 74 61 74 65 6d 65 6e 74 73 2c 0a 2a 2a  T statements,.**
38030 20 6f 72 20 6d 65 72 65 6c 79 20 63 61 6c 6c 69   or merely calli
38040 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
38050 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73  are_v2()] and [s
38060 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
38070 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
38080 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
38090 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
380a0 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
380b0 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
380c0 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  raph..**.** ^Reg
380d0 69 73 74 65 72 69 6e 67 20 61 20 4e 55 4c 4c 20  istering a NULL 
380e0 66 75 6e 63 74 69 6f 6e 20 64 69 73 61 62 6c 65  function disable
380f0 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 2e 0a  s the callback..
38100 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20  **.** ^When the 
38110 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 63 61 6c 6c  commit hook call
38120 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 74  back routine ret
38130 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 5b  urns zero, the [
38140 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 70 65 72 61  COMMIT].** opera
38150 74 69 6f 6e 20 69 73 20 61 6c 6c 6f 77 65 64 20  tion is allowed 
38160 74 6f 20 63 6f 6e 74 69 6e 75 65 20 6e 6f 72 6d  to continue norm
38170 61 6c 6c 79 2e 20 20 5e 49 66 20 74 68 65 20 63  ally.  ^If the c
38180 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a 2a 20 72 65  ommit hook.** re
38190 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
381a0 74 68 65 6e 20 74 68 65 20 5b 43 4f 4d 4d 49 54  then the [COMMIT
381b0 5d 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 69  ] is converted i
381c0 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42 41 43 4b 5d  nto a [ROLLBACK]
381d0 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61  ..** ^The rollba
381e0 63 6b 20 68 6f 6f 6b 20 69 73 20 69 6e 76 6f 6b  ck hook is invok
381f0 65 64 20 6f 6e 20 61 20 72 6f 6c 6c 62 61 63 6b  ed on a rollback
38200 20 74 68 61 74 20 72 65 73 75 6c 74 73 20 66 72   that results fr
38210 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a 2a 2a 20 68  om a commit.** h
38220 6f 6f 6b 20 72 65 74 75 72 6e 69 6e 67 20 6e 6f  ook returning no
38230 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74 20 61 73 20  n-zero, just as 
38240 69 74 20 77 6f 75 6c 64 20 62 65 20 77 69 74 68  it would be with
38250 20 61 6e 79 20 6f 74 68 65 72 20 72 6f 6c 6c 62   any other rollb
38260 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20  ack..**.** ^For 
38270 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20  the purposes of 
38280 74 68 69 73 20 41 50 49 2c 20 61 20 74 72 61 6e  this API, a tran
38290 73 61 63 74 69 6f 6e 20 69 73 20 73 61 69 64 20  saction is said 
382a0 74 6f 20 68 61 76 65 20 62 65 65 6e 0a 2a 2a 20  to have been.** 
382b0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 69 66 20 61  rolled back if a
382c0 6e 20 65 78 70 6c 69 63 69 74 20 22 52 4f 4c 4c  n explicit "ROLL
382d0 42 41 43 4b 22 20 73 74 61 74 65 6d 65 6e 74 20  BACK" statement 
382e0 69 73 20 65 78 65 63 75 74 65 64 2c 20 6f 72 0a  is executed, or.
382f0 2a 2a 20 61 6e 20 65 72 72 6f 72 20 6f 72 20 63  ** an error or c
38300 6f 6e 73 74 72 61 69 6e 74 20 63 61 75 73 65 73  onstraint causes
38310 20 61 6e 20 69 6d 70 6c 69 63 69 74 20 72 6f 6c   an implicit rol
38320 6c 62 61 63 6b 20 74 6f 20 6f 63 63 75 72 2e 0a  lback to occur..
38330 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c 62 61 63 6b  ** ^The rollback
38340 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 6e 6f 74   callback is not
38350 20 69 6e 76 6f 6b 65 64 20 69 66 20 61 20 74 72   invoked if a tr
38360 61 6e 73 61 63 74 69 6f 6e 20 69 73 0a 2a 2a 20  ansaction is.** 
38370 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f  automatically ro
38380 6c 6c 65 64 20 62 61 63 6b 20 62 65 63 61 75 73  lled back becaus
38390 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
383a0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
383b0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  sed..**.** See a
383c0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
383d0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 5d 20  _update_hook()] 
383e0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 53 51  interface..*/.SQ
383f0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
38400 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f  qlite3_commit_ho
38410 6f 6b 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ok(sqlite3*, int
38420 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
38430 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
38440 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c  oid *sqlite3_rol
38450 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74  lback_hook(sqlit
38460 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  e3*, void(*)(voi
38470 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  d *), void*);../
38480 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
38490 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66  ata Change Notif
384a0 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ication Callback
384b0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
384c0 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
384d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67  () interface reg
384e0 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63  isters a callbac
384f0 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  k function.** wi
38500 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  th the [database
38510 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65   connection] ide
38520 6e 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ntified by the f
38530 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a  irst argument.**
38540 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
38550 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73  henever a row is
38560 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74   updated, insert
38570 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a  ed or deleted..*
38580 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20  * ^Any callback 
38590 73 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75  set by a previou
385a0 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66  s call to this f
385b0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74  unction.** for t
385c0 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
385d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f   connection is o
385e0 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a  verridden..**.**
385f0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67   ^The second arg
38600 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
38610 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69  er to the functi
38620 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65  on to invoke whe
38630 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70  n a.** row is up
38640 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20  dated, inserted 
38650 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  or deleted..** ^
38660 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
38670 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  nt to the callba
38680 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ck is a copy of 
38690 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  the third argume
386a0 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  nt.** to sqlite3
386b0 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a  _update_hook()..
386c0 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63  ** ^The second c
386d0 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74  allback argument
386e0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
386f0 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c  TE_INSERT], [SQL
38700 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20  ITE_DELETE],.** 
38710 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54  or [SQLITE_UPDAT
38720 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  E], depending on
38730 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74   the operation t
38740 68 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63  hat caused the c
38750 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65  allback.** to be
38760 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68   invoked..** ^Th
38770 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72  e third and four
38780 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  th arguments to 
38790 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e  the callback con
387a0 74 61 69 6e 20 70 6f