System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 1dad6bdae57227224af8ce9eb9fb8a4673566c3e:


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 38 2e 32 22 0a 23 64 65 66 69 6e 65 20 53 51  .8.2".#define SQ
1030: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
1040: 42 45 52 20 33 30 30 38 30 30 32 0a 23 64 65 66  BER 3008002.#def
1050: 69 6e 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43  ine SQLITE_SOURC
1060: 45 5f 49 44 20 20 20 20 20 20 22 32 30 31 33 2d  E_ID      "2013-
1070: 31 32 2d 30 36 20 31 34 3a 35 33 3a 33 30 20 32  12-06 14:53:30 2
1080: 37 33 39 32 31 31 38 61 66 34 63 33 38 63 35 32  7392118af4c38c52
1090: 30 33 61 30 34 62 38 30 31 33 65 31 61 66 64 62  03a04b8013e1afdb
10a0: 31 63 65 62 64 30 64 22 0a 0a 2f 2a 0a 2a 2a 20  1cebd0d"../*.** 
10b0: 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
10c0: 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69  me Library Versi
10d0: 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45  on Numbers.** KE
10e0: 59 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f  YWORDS: sqlite3_
10f0: 76 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33  version, sqlite3
1100: 5f 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20  _sourceid.**.** 
1110: 54 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  These interfaces
1120: 20 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d   provide the sam
1130: 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73  e information as
1140: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52   the [SQLITE_VER
1150: 53 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  SION],.** [SQLIT
1160: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
1170: 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53  ], and [SQLITE_S
1180: 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70  OURCE_ID] C prep
1190: 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a  rocessor macros.
11a0: 2a 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63  ** but are assoc
11b0: 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c  iated with the l
11c0: 69 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f  ibrary instead o
11d0: 66 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c  f the header fil
11e0: 65 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a  e.  ^(Cautious.*
11f0: 2a 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69  * programmers mi
1200: 67 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65  ght include asse
1210: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20  rt() statements 
1220: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61  in their applica
1230: 74 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66  tion to.** verif
1240: 79 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65  y that values re
1250: 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1260: 69 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68  interfaces match
1270: 20 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a   the macros in.*
1280: 2a 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e  * the header, an
1290: 64 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68  d thus insure th
12a0: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
12b0: 6f 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  on is.** compile
12c0: 64 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20  d with matching 
12d0: 6c 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64  library and head
12e0: 65 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20  er files..**.** 
12f0: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1300: 3e 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c  >.** assert( sql
1310: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1320: 6e 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45  number()==SQLITE
1330: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
1340: 29 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74  );.** assert( st
1350: 72 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75  rcmp(sqlite3_sou
1360: 72 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53  rceid(),SQLITE_S
1370: 4f 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a  OURCE_ID)==0 );.
1380: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
1390: 70 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  p(sqlite3_libver
13a0: 73 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45  sion(),SQLITE_VE
13b0: 52 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20  RSION)==0 );.** 
13c0: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
13d0: 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  te>)^.**.** ^The
13e0: 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e   sqlite3_version
13f0: 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  [] string consta
1400: 6e 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  nt contains the 
1410: 74 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f  text of [SQLITE_
1420: 56 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72  VERSION].** macr
1430: 6f 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  o.  ^The sqlite3
1440: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75  _libversion() fu
1450: 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61  nction returns a
1460: 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a   pointer to the.
1470: 2a 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  ** to the sqlite
1480: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69  3_version[] stri
1490: 6e 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68  ng constant.  Th
14a0: 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72  e sqlite3_libver
14b0: 73 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69  sion().** functi
14c0: 6f 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66  on is provided f
14d0: 6f 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73  or use in DLLs s
14e0: 69 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75  ince DLL users u
14f0: 73 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61  sually do not ha
1500: 76 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63  ve.** direct acc
1510: 65 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f  ess to string co
1520: 6e 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74  nstants within t
1530: 68 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a  he DLL.  ^The.**
1540: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1550: 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e  ion_number() fun
1560: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e  ction returns an
1570: 20 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74   integer equal t
1580: 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52  o.** [SQLITE_VER
1590: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e  SION_NUMBER].  ^
15a0: 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72  The sqlite3_sour
15b0: 63 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  ceid() function 
15c0: 72 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f  returns .** a po
15d0: 69 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e  inter to a strin
15e0: 67 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65  g constant whose
15f0: 20 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61   value is the sa
1600: 6d 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53  me as the .** [S
1610: 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d  QLITE_SOURCE_ID]
1620: 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
1630: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  macro..**.** See
1640: 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76   also: [sqlite_v
1650: 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  ersion()] and [s
1660: 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28  qlite_source_id(
1670: 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
1680: 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  I SQLITE_EXTERN 
1690: 63 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74  const char sqlit
16a0: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 3b 0a 53 51  e3_version[];.SQ
16b0: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
16c0: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
16d0: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53  version(void);.S
16e0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
16f0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
1700: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51  urceid(void);.SQ
1710: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
1720: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
1730: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
1740: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1750: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
1760: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69  Compilation Opti
1770: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a  ons Diagnostics.
1780: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1790: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
17a0: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e  _used() function
17b0: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20   returns 0 or 1 
17c0: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77  .** indicating w
17d0: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69  hether the speci
17e0: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20  fied option was 
17f0: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63  defined at .** c
1800: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54  ompile time.  ^T
1810: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69  he SQLITE_ prefi
1820: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  x may be omitted
1830: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70   from the .** op
1840: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64  tion name passed
1850: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
1860: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
1870: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .  .**.** ^The s
1880: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1890: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74  tion_get() funct
18a0: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61  ion allows itera
18b0: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65  ting.** over the
18c0: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73   list of options
18d0: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e   that were defin
18e0: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  ed at compile ti
18f0: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69  me by.** returni
1900: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70  ng the N-th comp
1910: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile time option 
1920: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69  string.  ^If N i
1930: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a  s out of range,.
1940: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
1950: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72  leoption_get() r
1960: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1970: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c  inter.  ^The SQL
1980: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20  ITE_ .** prefix 
1990: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
19a0: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75  any strings retu
19b0: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  rned by .** sqli
19c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19d0: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  n_get()..**.** ^
19e0: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20  Support for the 
19f0: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74  diagnostic funct
1a00: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ions sqlite3_com
1a10: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a20: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ).** and sqlite3
1a30: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1a40: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74  et() may be omit
1a50: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e  ted by specifyin
1a60: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  g the .** [SQLIT
1a70: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
1a80: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69  TION_DIAGS] opti
1a90: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  on at compile ti
1aa0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  me..**.** See al
1ab0: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  so: SQL function
1ac0: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  s [sqlite_compil
1ad0: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20  eoption_used()] 
1ae0: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63  and.** [sqlite_c
1af0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
1b00: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d  ()] and the [com
1b10: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61  pile_options pra
1b20: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  gma]..*/.#ifndef
1b30: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
1b40: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
1b50: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1b60: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
1b70: 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74  ption_used(const
1b80: 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29   char *zOptName)
1b90: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
1ba0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
1bb0: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
1bc0: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
1bd0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
1be0: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
1bf0: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
1c00: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
1c10: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1c20: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
1c30: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
1c40: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
1c50: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
1c60: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
1c70: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74  exing code omitt
1c80: 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a  ed due to the.**
1c90: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
1ca0: 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AFE] compile-tim
1cb0: 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73  e option being s
1cc0: 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53  et to 0..**.** S
1cd0: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d  QLite can be com
1ce0: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69  piled with or wi
1cf0: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20  thout mutexes.  
1d00: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  When.** the [SQL
1d10: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1d20: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
1d30: 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20  acro is 1 or 2, 
1d40: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
1d50: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74  nabled and SQLit
1d60: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e  e is threadsafe.
1d70: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53    When the.** [S
1d80: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1d90: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a  ] macro is 0, .*
1da0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72  * the mutexes ar
1db0: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68  e omitted.  With
1dc0: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c  out the mutexes,
1dd0: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a   it is not safe.
1de0: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65  ** to use SQLite
1df0: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72   concurrently fr
1e00: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  om more than one
1e10: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45   thread..**.** E
1e20: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20  nabling mutexes 
1e30: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61  incurs a measura
1e40: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ble performance 
1e50: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69  penalty..** So i
1e60: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74  f speed is of ut
1e70: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c  most importance,
1e80: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20   it makes sense 
1e90: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  to disable.** th
1ea0: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20  e mutexes.  But 
1eb0: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65  for maximum safe
1ec0: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ty, mutexes shou
1ed0: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  ld be enabled..*
1ee0: 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1ef0: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
1f00: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
1f10: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
1f20: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
1f30: 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70  e used by an app
1f40: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65  lication to make
1f50: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a   sure that the.*
1f60: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  * version of SQL
1f70: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c  ite that it is l
1f80: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77  inking against w
1f90: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
1fa0: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20  .** the desired 
1fb0: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b  setting of the [
1fc0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
1fd0: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  E] macro..**.** 
1fe0: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f  This interface o
1ff0: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74  nly reports on t
2000: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
2010: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a  mutex setting.**
2020: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
2030: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67  THREADSAFE] flag
2040: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
2050: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
2060: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
2070: 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20  FE=1 or =2 then 
2080: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
2090: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
20a0: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
20b0: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
20c0: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
20d0: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
20e0: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
20f0: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
2100: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
2110: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
2120: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
2130: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
2140: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
2150: 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74  TEX].  ^(The ret
2160: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
2170: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65  .** sqlite3_thre
2180: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
2190: 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65  n shows only the
21a0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65   compile-time se
21b0: 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65  tting of.** thre
21c0: 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61  ad safety, not a
21d0: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e  ny run-time chan
21e0: 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74  ges to that sett
21f0: 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73  ing made by.** s
2200: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
2210: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2220: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2230: 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74  e from sqlite3_t
2240: 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69  hreadsafe().** i
2250: 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63  s unchanged by c
2260: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
2270: 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a  config().)^.**.*
2280: 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61  * See the [threa
2290: 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d  ding mode] docum
22a0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
22b0: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
22c0: 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
22d0: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
22e0: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b  hreadsafe(void);
22f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2300: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
2310: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20  ction Handle.** 
2320: 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62  KEYWORDS: {datab
2330: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20  ase connection} 
2340: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
2350: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63  tions}.**.** Eac
2360: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
2370: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
2380: 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74  ented by a point
2390: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
23a0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71  e of.** the opaq
23b0: 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d  ue structure nam
23c0: 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49  ed "sqlite3".  I
23d0: 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74  t is useful to t
23e0: 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74  hink of an sqlit
23f0: 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73  e3.** pointer as
2400: 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65   an object.  The
2410: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
2420: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
2430: 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  16()], and.** [s
2440: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
2450: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ] interfaces are
2460: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72   its constructor
2470: 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  s, and [sqlite3_
2480: 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20  close()].** and 
2490: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76  [sqlite3_close_v
24a0: 32 28 29 5d 20 61 72 65 20 69 74 73 20 64 65 73  2()] are its des
24b0: 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65  tructors.  There
24c0: 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a   are many other.
24d0: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28 73  ** interfaces (s
24e0: 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74  uch as.** [sqlit
24f0: 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2500: 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
2510: 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61  e_function()], a
2520: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
2530: 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74  usy_timeout()] t
2540: 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65  o name but three
2550: 29 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f  ) that are metho
2560: 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ds on an.** sqli
2570: 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74  te3 object..*/.t
2580: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
2590: 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a  lite3 sqlite3;..
25a0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
25b0: 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54  64-Bit Integer T
25c0: 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
25d0: 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73  : sqlite_int64 s
25e0: 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a  qlite_uint64.**.
25f0: 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65  ** Because there
2600: 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61   is no cross-pla
2610: 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65  tform way to spe
2620: 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65  cify 64-bit inte
2630: 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c  ger types.** SQL
2640: 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70  ite includes typ
2650: 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74  edefs for 64-bit
2660: 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69   signed and unsi
2670: 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a  gned integers..*
2680: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
2690: 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74  _int64 and sqlit
26a0: 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68  e3_uint64 are th
26b0: 65 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65  e preferred type
26c0: 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a   definitions..**
26d0: 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36   The sqlite_int6
26e0: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
26f0: 74 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75  t64 types are su
2700: 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b  pported for back
2710: 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69  wards.** compati
2720: 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a  bility only..**.
2730: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2740: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2750: 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e  _int64 types can
2760: 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76   store integer v
2770: 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e  alues.** between
2780: 20 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37   -92233720368547
2790: 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33  75808 and +92233
27a0: 37 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69  72036854775807 i
27b0: 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a  nclusive.  ^The.
27c0: 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  ** sqlite3_uint6
27d0: 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e  4 and sqlite_uin
27e0: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
27f0: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
2800: 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30  es .** between 0
2810: 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37   and +1844674407
2820: 33 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75  3709551615 inclu
2830: 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  sive..*/.#ifdef 
2840: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
2850: 45 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49  E.  typedef SQLI
2860: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
2870: 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79  lite_int64;.  ty
2880: 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53  pedef unsigned S
2890: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
28a0: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a   sqlite_uint64;.
28b0: 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d  #elif defined(_M
28c0: 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e  SC_VER) || defin
28d0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
28e0: 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74  .  typedef __int
28f0: 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b  64 sqlite_int64;
2900: 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67  .  typedef unsig
2910: 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69  ned __int64 sqli
2920: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65  te_uint64;.#else
2930: 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20  .  typedef long 
2940: 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f  long int sqlite_
2950: 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66  int64;.  typedef
2960: 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c   unsigned long l
2970: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75  ong int sqlite_u
2980: 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79  int64;.#endif.ty
2990: 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74  pedef sqlite_int
29a0: 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  64 sqlite3_int64
29b0: 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  ;.typedef sqlite
29c0: 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  _uint64 sqlite3_
29d0: 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49  uint64;../*.** I
29e0: 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20  f compiling for 
29f0: 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74  a processor that
2a00: 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20   lacks floating 
2a10: 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a  point support,.*
2a20: 2a 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74  * substitute int
2a30: 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e  eger for floatin
2a40: 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64  g-point..*/.#ifd
2a50: 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46  ef SQLITE_OMIT_F
2a60: 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20  LOATING_POINT.# 
2a70: 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71  define double sq
2a80: 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64  lite3_int64.#end
2a90: 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  if../*.** CAPI3R
2aa0: 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61  EF: Closing A Da
2ab0: 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f  tabase Connectio
2ac0: 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  n.**.** ^The sql
2ad0: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64  ite3_close() and
2ae0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2af0: 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65  2() routines are
2b00: 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20   destructors.** 
2b10: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
2b20: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61  ] object..** ^Ca
2b30: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2b40: 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lose() and sqlit
2b50: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65  e3_close_v2() re
2b60: 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69  turn SQLITE_OK i
2b70: 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  f.** the [sqlite
2b80: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63  3] object is suc
2b90: 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f  cessfully destro
2ba0: 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f  yed and all asso
2bb0: 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72  ciated.** resour
2bc0: 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61  ces are dealloca
2bd0: 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ted..**.** ^If t
2be0: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2bf0: 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69  ection is associ
2c00: 61 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61  ated with unfina
2c10: 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a  lized prepared.*
2c20: 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20  * statements or 
2c30: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
2c40: 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74  e3_backup object
2c50: 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  s then sqlite3_c
2c60: 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c  lose().** will l
2c70: 65 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73  eave the databas
2c80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
2c90: 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  n and return [SQ
2ca0: 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e  LITE_BUSY]..** ^
2cb0: 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  If sqlite3_close
2cc0: 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20  _v2() is called 
2cd0: 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64  with unfinalized
2ce0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2cf0: 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69  ents.** and unfi
2d00: 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62  nished sqlite3_b
2d10: 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65  ackups, then the
2d20: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
2d30: 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20  tion becomes.** 
2d40: 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d  an unusable "zom
2d50: 62 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20  bie" which will 
2d60: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65  automatically be
2d70: 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65   deallocated whe
2d80: 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72  n the.** last pr
2d90: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2da0: 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72   is finalized or
2db0: 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
2dc0: 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66  3_backup is.** f
2dd0: 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71  inished.  The sq
2de0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
2df0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e   interface is in
2e00: 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77  tended for use w
2e10: 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67  ith.** host lang
2e20: 75 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67  uages that are g
2e30: 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64  arbage collected
2e40: 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20  , and where the 
2e50: 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a  order in which.*
2e60: 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72  * destructors ar
2e70: 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69  e called is arbi
2e80: 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  trary..**.** App
2e90: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2ea0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2eb0: 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61  ze | finalize] a
2ec0: 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ll [prepared sta
2ed0: 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71  tements],.** [sq
2ee0: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
2ef0: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
2f00: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e  LOB handles], an
2f10: 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  d .** [sqlite3_b
2f20: 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66  ackup_finish | f
2f30: 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69  inish] all [sqli
2f40: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
2f50: 63 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  cts associated.*
2f60: 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69  * with the [sqli
2f70: 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f  te3] object prio
2f80: 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20  r to attempting 
2f90: 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a  to close the obj
2fa0: 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c  ect.  ^If.** sql
2fb0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
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 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
3f50: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
3f60: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
3f70: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
3f80: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3f90: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3fa0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3fb0: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ning..** <li> Th
3fc0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
3fd0: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  st not modify th
3fe0: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
3ff0: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f  text passed into
4000: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64  .**      the 2nd
4010: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
4020: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
4030: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
4040: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
4050: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ul>.*/.SQLITE
4060: 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
4070: 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33  _exec(.  sqlite3
4080: 2a 2c 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: 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64      /* An open d
40b0: 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e  atabase */.  con
40c0: 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20  st char *sql,   
40d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40e0: 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74          /* SQL t
40f0: 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
4100: 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61  /.  int (*callba
4110: 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68  ck)(void*,int,ch
4120: 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f  ar**,char**),  /
4130: 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * Callback funct
4140: 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c  ion */.  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: 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d      /* 1st argum
4180: 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20  ent to callback 
4190: 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d  */.  char **errm
41a0: 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20  sg              
41b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
41c0: 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
41d0: 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
41e0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
41f0: 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a   Result Codes.**
4200: 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54   KEYWORDS: SQLIT
4210: 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65  E_OK {error code
4220: 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a  } {error codes}.
4230: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65  ** KEYWORDS: {re
4240: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75  sult code} {resu
4250: 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20  lt codes}.**.** 
4260: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
4270: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
4280: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
4290: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
42a0: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69   shown.** here i
42b0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
42c0: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66  ate success or f
42d0: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
42e0: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
42f0: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
4300: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
4310: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
4320: 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45  ee also: [SQLITE
4330: 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78  _IOERR_READ | ex
4340: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4350: 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  des],.** [sqlite
4360: 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
4370: 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f  ct()] [SQLITE_RO
4380: 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20  LLBACK | result 
4390: 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69  codes]..*/.#defi
43a0: 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20  ne SQLITE_OK    
43b0: 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75         0   /* Su
43c0: 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20  ccessful result 
43d0: 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d  */./* beginning-
43e0: 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a  of-error-codes *
43f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4400: 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20  _ERROR        1 
4410: 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f    /* SQL error o
4420: 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61  r missing databa
4430: 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  se */.#define SQ
4440: 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20  LITE_INTERNAL   
4450: 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61    2   /* Interna
4460: 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e  l logic error in
4470: 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69   SQLite */.#defi
4480: 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20  ne SQLITE_PERM  
4490: 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63         3   /* Ac
44a0: 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20  cess permission 
44b0: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
44c0: 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20  e SQLITE_ABORT  
44d0: 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c        4   /* Cal
44e0: 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65  lback routine re
44f0: 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74  quested an abort
4500: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4510: 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20  TE_BUSY         
4520: 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  5   /* The datab
4530: 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b  ase file is lock
4540: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4550: 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20  LITE_LOCKED     
4560: 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65    6   /* A table
4570: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
4580: 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64   is locked */.#d
4590: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d  efine SQLITE_NOM
45a0: 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a  EM        7   /*
45b0: 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c   A malloc() fail
45c0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
45d0: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20  LITE_READONLY   
45e0: 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74    8   /* Attempt
45f0: 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64   to write a read
4600: 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f  only database */
4610: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4620: 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20  INTERRUPT    9  
4630: 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65   /* Operation te
4640: 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69  rminated by sqli
4650: 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a  te3_interrupt()*
4660: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4670: 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20  _IOERR       10 
4680: 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f    /* Some kind o
4690: 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72  f disk I/O error
46a0: 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65   occurred */.#de
46b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52  fine SQLITE_CORR
46c0: 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20  UPT     11   /* 
46d0: 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73  The database dis
46e0: 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f  k image is malfo
46f0: 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rmed */.#define 
4700: 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20  SQLITE_NOTFOUND 
4710: 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f     12   /* Unkno
4720: 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c  wn opcode in sql
4730: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
4740: 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  l() */.#define S
4750: 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20  QLITE_FULL      
4760: 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74    13   /* Insert
4770: 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75  ion failed becau
4780: 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66  se database is f
4790: 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ull */.#define S
47a0: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20  QLITE_CANTOPEN  
47b0: 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65    14   /* Unable
47c0: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
47d0: 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64  abase file */.#d
47e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f  efine SQLITE_PRO
47f0: 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a  TOCOL    15   /*
4800: 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70   Database lock p
4810: 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f  rotocol error */
4820: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4830: 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20  EMPTY       16  
4840: 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20   /* Database is 
4850: 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65  empty */.#define
4860: 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20   SQLITE_SCHEMA  
4870: 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20      17   /* The 
4880: 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20  database schema 
4890: 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69  changed */.#defi
48a0: 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47  ne SQLITE_TOOBIG
48b0: 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74        18   /* St
48c0: 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63  ring or BLOB exc
48d0: 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20  eeds size limit 
48e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
48f0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39  E_CONSTRAINT  19
4900: 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20     /* Abort due 
4910: 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69  to constraint vi
4920: 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69  olation */.#defi
4930: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54  ne SQLITE_MISMAT
4940: 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61  CH    20   /* Da
4950: 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68  ta type mismatch
4960: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4970: 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32  TE_MISUSE      2
4980: 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75  1   /* Library u
4990: 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20  sed incorrectly 
49a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
49b0: 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32  E_NOLFS       22
49c0: 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65     /* Uses OS fe
49d0: 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f  atures not suppo
49e0: 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a  rted on host */.
49f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
4a00: 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20  UTH        23   
4a10: 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  /* Authorization
4a20: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4a30: 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54  ne SQLITE_FORMAT
4a40: 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75        24   /* Au
4a50: 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65  xiliary database
4a60: 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f   format error */
4a70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a80: 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20  RANGE       25  
4a90: 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65   /* 2nd paramete
4aa0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  r to sqlite3_bin
4ab0: 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a  d out of range *
4ac0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4ad0: 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20  _NOTADB      26 
4ae0: 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64    /* File opened
4af0: 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64   that is not a d
4b00: 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a  atabase file */.
4b10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e  #define SQLITE_N
4b20: 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20 20  OTICE      27   
4b30: 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e 73  /* Notifications
4b40: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c 6f   from sqlite3_lo
4b50: 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  g() */.#define S
4b60: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20 20  QLITE_WARNING   
4b70: 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69 6e    28   /* Warnin
4b80: 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  gs from sqlite3_
4b90: 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65  log() */.#define
4ba0: 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20 20   SQLITE_ROW     
4bb0: 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c 69      100  /* sqli
4bc0: 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 61  te3_step() has a
4bd0: 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64 79  nother row ready
4be0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4bf0: 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20 31  TE_DONE        1
4c00: 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73  01  /* sqlite3_s
4c10: 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73 68  tep() has finish
4c20: 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a  ed executing */.
4c30: 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d  /* end-of-error-
4c40: 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  codes */../*.** 
4c50: 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e 64  CAPI3REF: Extend
4c60: 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
4c70: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78  ** KEYWORDS: {ex
4c80: 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
4c90: 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72  e} {extended err
4ca0: 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59  or codes}.** KEY
4cb0: 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65 64  WORDS: {extended
4cc0: 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65   result code} {e
4cd0: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4ce0: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69  odes}.**.** In i
4cf0: 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69  ts default confi
4d00: 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65  guration, SQLite
4d10: 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65   API routines re
4d20: 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69  turn one of 26 i
4d30: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
4d40: 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f  E_OK | result co
4d50: 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20  des].  However, 
4d60: 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20 73  experience has s
4d70: 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f  hown that many o
4d80: 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75 6c  f.** these resul
4d90: 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f 20  t codes are too 
4da0: 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e 20  coarse-grained. 
4db0: 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f   They do not pro
4dc0: 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20  vide as.** much 
4dd0: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  information abou
4de0: 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70 72  t problems as pr
4df0: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
4e00: 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66 66  like.  In an eff
4e10: 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73  ort to.** addres
4e20: 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76 65  s this, newer ve
4e30: 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
4e40: 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20   (version 3.3.8 
4e50: 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c 75  and later) inclu
4e60: 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f  de.** support fo
4e70: 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65 73  r additional res
4e80: 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20 70  ult codes that p
4e90: 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74 61  rovide more deta
4ea0: 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  iled information
4eb0: 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72 73  .** about errors
4ec0: 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20 72  . The extended r
4ed0: 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20  esult codes are 
4ee0: 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62  enabled or disab
4ef0: 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20  led.** on a per 
4f00: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
4f10: 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67 20  ion basis using 
4f20: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
4f30: 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
4f40: 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a  codes()] API..**
4f50: 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20  .** Some of the 
4f60: 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e 64  available extend
4f70: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4f80: 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65 2e  are listed here.
4f90: 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70 65  .** One may expe
4fa0: 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ct the number of
4fb0: 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
4fc0: 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63 72   codes will incr
4fd0: 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69 6d  ease.** over tim
4fe0: 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  e.  Software tha
4ff0: 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64 20  t uses extended 
5000: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f  result codes sho
5010: 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f  uld expect.** to
5020: 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20   see new result 
5030: 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65 20  codes in future 
5040: 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
5050: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  te..**.** The SQ
5060: 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63  LITE_OK result c
5070: 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62  ode will never b
5080: 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20  e extended.  It 
5090: 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62  will always.** b
50a0: 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a  e exactly zero..
50b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
50c0: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20  E_IOERR_READ    
50d0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
50e0: 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29  E_IOERR | (1<<8)
50f0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5100: 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41  _IOERR_SHORT_REA
5110: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
5120: 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29  _IOERR | (2<<8))
5130: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5140: 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20  IOERR_WRITE     
5150: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5160: 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a  IOERR | (3<<8)).
5170: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5180: 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20  OERR_FSYNC      
5190: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
51a0: 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23  OERR | (4<<8)).#
51b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
51c0: 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20  ERR_DIR_FSYNC   
51d0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
51e0: 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64  ERR | (5<<8)).#d
51f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5200: 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20  RR_TRUNCATE     
5210: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5220: 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65  RR | (6<<8)).#de
5230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5240: 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20  R_FSTAT         
5250: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5260: 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66  R | (7<<8)).#def
5270: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5280: 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _UNLOCK         
5290: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52a0: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52c0: 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  RDLOCK          
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52e0: 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (9<<8)).#defin
52f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
5300: 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
5310: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5320: 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (10<<8)).#defin
5330: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42  e SQLITE_IOERR_B
5340: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20  LOCKED          
5350: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5360: 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (11<<8)).#defin
5370: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e  e SQLITE_IOERR_N
5380: 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20  OMEM            
5390: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
53a0: 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (12<<8)).#defin
53b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41  e SQLITE_IOERR_A
53c0: 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20  CCESS           
53d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
53e0: 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (13<<8)).#defin
53f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
5400: 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b  HECKRESERVEDLOCK
5410: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5420: 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (14<<8)).#defin
5430: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c  e SQLITE_IOERR_L
5440: 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  OCK             
5450: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5460: 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (15<<8)).#defin
5470: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
5480: 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20  LOSE            
5490: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
54a0: 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (16<<8)).#defin
54b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
54c0: 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  IR_CLOSE        
54d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
54e0: 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (17<<8)).#defin
54f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
5500: 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20  HMOPEN          
5510: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5520: 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (18<<8)).#defin
5530: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
5540: 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20  HMSIZE          
5550: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5560: 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (19<<8)).#defin
5570: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
5580: 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  HMLOCK          
5590: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
55a0: 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (20<<8)).#defin
55b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
55c0: 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  HMMAP           
55d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
55e0: 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (21<<8)).#defin
55f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  e SQLITE_IOERR_S
5600: 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  EEK             
5610: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5620: 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (22<<8)).#defin
5630: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44  e SQLITE_IOERR_D
5640: 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20  ELETE_NOENT     
5650: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5660: 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (23<<8)).#defin
5670: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d  e SQLITE_IOERR_M
5680: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20  MAP             
5690: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
56a0: 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (24<<8)).#defin
56b0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47  e SQLITE_IOERR_G
56c0: 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20  ETTEMPPATH      
56d0: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
56e0: 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (25<<8)).#defin
56f0: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43  e SQLITE_IOERR_C
5700: 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20  ONVPATH         
5710: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5720: 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e   (26<<8)).#defin
5730: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f  e SQLITE_LOCKED_
5740: 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20  SHAREDCACHE     
5750: 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20   (SQLITE_LOCKED 
5760: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5770: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52  ne SQLITE_BUSY_R
5780: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20  ECOVERY         
5790: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20    (SQLITE_BUSY  
57a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
57b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
57c0: 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20  SNAPSHOT        
57d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
57e0: 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65    |  (2<<8)).#de
57f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
5800: 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20  OPEN_NOTEMPDIR  
5810: 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54      (SQLITE_CANT
5820: 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23  OPEN | (1<<8)).#
5830: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5840: 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20  NTOPEN_ISDIR    
5850: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5860: 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29  NTOPEN | (2<<8))
5870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5880: 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54  CANTOPEN_FULLPAT
5890: 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  H       (SQLITE_
58a0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38  CANTOPEN | (3<<8
58b0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
58c0: 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50  E_CANTOPEN_CONVP
58d0: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
58e0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c  E_CANTOPEN | (4<
58f0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5900: 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42  ITE_CORRUPT_VTAB
5910: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
5920: 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31  ITE_CORRUPT | (1
5930: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5940: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45  LITE_READONLY_RE
5950: 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51  COVERY       (SQ
5960: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5970: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
5980: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
5990: 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28  CANTLOCK       (
59a0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
59b0: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
59c0: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
59d0: 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  Y_ROLLBACK      
59e0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
59f0: 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  Y | (3<<8)).#def
5a00: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
5a10: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
5a20: 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54     (SQLITE_ABORT
5a30: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5a40: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5a50: 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20  AINT_CHECK      
5a60: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a70: 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AINT | (1<<8)).#
5a80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a90: 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48  NSTRAINT_COMMITH
5aa0: 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  OOK   (SQLITE_CO
5ab0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38  NSTRAINT | (2<<8
5ac0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5ad0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52  E_CONSTRAINT_FOR
5ae0: 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54  EIGNKEY   (SQLIT
5af0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5b00: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
5b10: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b20: 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53  _FUNCTION     (S
5b30: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5b40: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
5b50: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5b60: 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20  AINT_NOTNULL    
5b70: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5b80: 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23  AINT | (5<<8)).#
5b90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5ba0: 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59  NSTRAINT_PRIMARY
5bb0: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
5bc0: 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38  NSTRAINT | (6<<8
5bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5be0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49  E_CONSTRAINT_TRI
5bf0: 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 54  GGER      (SQLIT
5c00: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5c10: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
5c20: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c30: 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 53  _UNIQUE       (S
5c40: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
5c50: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
5c60: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
5c70: 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20  AINT_VTAB       
5c80: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5c90: 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 23  AINT | (9<<8)).#
5ca0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5cb0: 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20 20  NSTRAINT_ROWID  
5cc0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5cd0: 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c 38  NSTRAINT |(10<<8
5ce0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5cf0: 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52  E_NOTICE_RECOVER
5d00: 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49 54  _WAL      (SQLIT
5d10: 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c 38  E_NOTICE | (1<<8
5d20: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d30: 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45 52  E_NOTICE_RECOVER
5d40: 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49 54  _ROLLBACK (SQLIT
5d50: 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c 38  E_NOTICE | (2<<8
5d60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5d70: 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49 4e  E_WARNING_AUTOIN
5d80: 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49 54  DEX       (SQLIT
5d90: 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c 3c  E_WARNING | (1<<
5da0: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
5db0: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
5dc0: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
5dd0: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
5de0: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
5df0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
5e00: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
5e10: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
5e20: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
5e30: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
5e40: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
5e50: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5e60: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
5e70: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23  en] method..*/.#
5e80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5e90: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
5ea0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20      0x00000001  
5eb0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5ec0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5ed0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5ee0: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
5ef0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20      0x00000002  
5f00: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5f10: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5f20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5f30: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
5f40: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20      0x00000004  
5f50: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
5f60: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
5f70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5f80: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
5f90: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20      0x00000008  
5fa0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
5fc0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
5fd0: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20      0x00000010  
5fe0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
5ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6000: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20  EN_AUTOPROXY    
6010: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20      0x00000020  
6020: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6030: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6040: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  EN_URI          
6050: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20      0x00000040  
6060: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6070: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6080: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6090: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20  EN_MEMORY       
60a0: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20      0x00000080  
60b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
60c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
60d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
60e0: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
60f0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20      0x00000100  
6100: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6120: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
6130: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20      0x00000200  
6140: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6150: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6160: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
6170: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20      0x00000400  
6180: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6190: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
61a0: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
61b0: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20      0x00000800  
61c0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
61d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
61e0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
61f0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20      0x00001000  
6200: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6210: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6220: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
6230: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20      0x00002000  
6240: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6250: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6260: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
6270: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20  L   0x00004000  
6280: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
6290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62a0: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
62b0: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20      0x00008000  
62c0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
62d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
62e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
62f0: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
6300: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20      0x00010000  
6310: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6320: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6330: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6340: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  EN_SHAREDCACHE  
6350: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20      0x00020000  
6360: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
6370: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
6380: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
6390: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
63a0: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20      0x00040000  
63b0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
63c0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
63d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
63e0: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  EN_WAL          
63f0: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20      0x00080000  
6400: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a  /* VFS only */..
6410: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20  /* Reserved:    
6420: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
6430: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20       0x00F00000 
6440: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
6450: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
6460: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  cteristics.**.**
6470: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
6480: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
6490: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
64a0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
64b0: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
64c0: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
64d0: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
64e0: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
64f0: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
6500: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
6510: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
6520: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
6530: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
6540: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
6550: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6560: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
6570: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
6580: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
6590: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
65a0: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
65b0: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
65c0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
65d0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
65e0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
65f0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
6600: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
6610: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
6620: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
6630: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
6640: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
6650: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
6660: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
6670: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
6680: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6690: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
66a0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
66b0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
66c0: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
66d0: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
66e0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
66f0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
6700: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
6710: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
6720: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
6730: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
6740: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
6750: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
6760: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
6770: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
6780: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
6790: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
67a0: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20  * to xWrite().  
67b0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
67c0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
67d0: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65  RITE property me
67e0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65  ans that.** afte
67f0: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69  r reboot followi
6800: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f  ng a crash or po
6810: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e  wer loss, the on
6820: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a  ly bytes in a.**
6830: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20   file that were 
6840: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61  written at the a
6850: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c  pplication level
6860: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e   might have chan
6870: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ged.** and that 
6880: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20  adjacent bytes, 
6890: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69  even bytes withi
68a0: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f  n the same secto
68b0: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74  r are.** guarant
68c0: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e  eed to be unchan
68d0: 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ged..*/.#define 
68e0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
68f0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
6900: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
6910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6920: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
6930: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6940: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6950: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6960: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
6970: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
6980: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6990: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
69a0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
69b0: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
69c0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
69d0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
69e0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
69f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6a00: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
6a10: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
6a20: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6a30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6a40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6a50: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
6a60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6a70: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
6a80: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
6a90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6aa0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
6ab0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6ac0: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
6ad0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
6ae0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
6af0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
6b00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6b10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
6b20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
6b30: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
6b40: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6b50: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
6b60: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
6b70: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6b80: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6b90: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
6ba0: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
6bb0: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67  EF: File Locking
6bc0: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51   Levels.**.** SQ
6bd0: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
6be0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
6bf0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
6c00: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
6c10: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
6c20: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
6c30: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
6c40: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
6c50: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6c60: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
6c70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6c80: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
6c90: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
6ca0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
6cb0: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
6cc0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
6cd0: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
6ce0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6cf0: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
6d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6d10: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
6d20: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
6d30: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
6d40: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a  tion Type Flags.
6d50: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
6d60: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
6d70: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
6d80: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
6d90: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
6da0: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
6db0: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68  ination of.** th
6dc0: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
6dd0: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
6de0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
6df0: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   When the SQLITE
6e00: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66  _SYNC_DATAONLY f
6e10: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20  lag is used, it 
6e20: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a  means that the.*
6e30: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  * sync operation
6e40: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66   only needs to f
6e50: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73  lush data to mas
6e60: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64  s storage.  Inod
6e70: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
6e80: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75   need not be flu
6e90: 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77  shed. If the low
6ea0: 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20  er four bits of 
6eb0: 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61  the flag.** equa
6ec0: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  l SQLITE_SYNC_NO
6ed0: 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  RMAL, that means
6ee0: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66   to use normal f
6ef0: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73  sync() semantics
6f00: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65  ..** If the lowe
6f10: 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61  r four bits equa
6f20: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  l SQLITE_SYNC_FU
6f30: 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  LL, that means.*
6f40: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20  * to use Mac OS 
6f50: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
6f60: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e   instead of fsyn
6f70: 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f  c()..**.** Do no
6f80: 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51  t confuse the SQ
6f90: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
6fa0: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
6fb0: 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77  _FULL flags.** w
6fc0: 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20  ith the [PRAGMA 
6fd0: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52  synchronous]=NOR
6fe0: 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  MAL and [PRAGMA 
6ff0: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c  synchronous]=FUL
7000: 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20  L.** settings.  
7010: 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73  The [synchronous
7020: 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69   pragma] determi
7030: 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74  nes when calls t
7040: 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56  o the.** xSync V
7050: 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20  FS method occur 
7060: 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66  and applies unif
7070: 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c  ormly across all
7080: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54   platforms..** T
7090: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
70a0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
70b0: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
70c0: 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a   determine how.*
70d0: 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72  * energetic or r
70e0: 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65  igorous or force
70f0: 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65  ful the sync ope
7100: 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a  rations are and.
7110: 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64  ** only make a d
7120: 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63  ifference on Mac
7130: 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66   OSX for the def
7140: 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65  ault SQLite code
7150: 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74  ..** (Third-part
7160: 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  y VFS implementa
7170: 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f  tions might also
7180: 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
7190: 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e  ction.** between
71a0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
71b0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
71c0: 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d  YNC_FULL, but am
71d0: 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61  ong the.** opera
71e0: 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74  ting systems nat
71f0: 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20  ively supported 
7200: 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20  by SQLite, only 
7210: 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73  Mac OSX.** cares
7220: 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65   about the diffe
7230: 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69  rence.).*/.#defi
7240: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  ne SQLITE_SYNC_N
7250: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30  ORMAL        0x0
7260: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
7270: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20  ITE_SYNC_FULL   
7280: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23         0x00003.#
7290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
72a0: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20  NC_DATAONLY     
72b0: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20   0x00010../*.** 
72c0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
72d0: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65  erface Open File
72e0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e   Handle.**.** An
72f0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
7300: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
7310: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
7320: 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  n the .** [sqlit
7330: 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65  e3_vfs | OS inte
7340: 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49  rface layer].  I
7350: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74  ndividual OS int
7360: 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d  erface.** implem
7370: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
7380: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
7390: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
73a0: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
73b0: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
73c0: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75   for their own u
73d0: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64  se.  The pMethod
73e0: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69  s entry is a poi
73f0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
7400: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
7410: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
7420: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66  efines methods f
7430: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a  or performing.**
7440: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
7450: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  on the open file
7460: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
7470: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
7480: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73   sqlite3_file;.s
7490: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
74a0: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72  le {.  const str
74b0: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
74c0: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
74d0: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f  ;  /* Methods fo
74e0: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a  r an open file *
74f0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
7500: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
7510: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
7520: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a  Methods Object.*
7530: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20  *.** Every file 
7540: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73  opened by the [s
7550: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
7560: 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74  ] method populat
7570: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  es an.** [sqlite
7580: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28  3_file] object (
7590: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c  or, more commonl
75a0: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66  y, a subclass of
75b0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
75c0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77  _file] object) w
75d0: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ith a pointer to
75e0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
75f0: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  this object..** 
7600: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  This object defi
7610: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20  nes the methods 
7620: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20  used to perform 
7630: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f  various operatio
7640: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68  ns.** against th
7650: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72  e open file repr
7660: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b  esented by the [
7670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
7680: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ject..**.** If t
7690: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
76a0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65  xOpen] method se
76b0: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  ts the sqlite3_f
76c0: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
76d0: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f  ment .** to a no
76e0: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
76f0: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
7700: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f  _io_methods.xClo
7710: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79  se method.** may
7720: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e   be invoked even
7730: 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   if the [sqlite3
7740: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f  _vfs.xOpen] repo
7750: 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69  rted that it fai
7760: 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c  led.  The.** onl
7770: 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74  y way to prevent
7780: 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73   a call to xClos
7790: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  e following a fa
77a0: 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66  iled [sqlite3_vf
77b0: 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66  s.xOpen].** is f
77c0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
77d0: 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65  vfs.xOpen] to se
77e0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
77f0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
7800: 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a  ent.** to NULL..
7810: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
7820: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
7830: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
7840: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
7850: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
7860: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
7870: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
7880: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
7890: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
78a0: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
78b0: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  a Mac OS X style
78c0: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
78d0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
78e0: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
78f0: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
7900: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
7910: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
7920: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
7930: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
7940: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
7950: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
7960: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
7970: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
7980: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
7990: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
79a0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
79b0: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
79c0: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
79d0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
79e0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
79f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7a00: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
7a10: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
7a20: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
7a30: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
7a40: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
7a50: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
7a60: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
7a70: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
7a80: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
7a90: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
7aa0: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
7ab0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
7ac0: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
7ad0: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
7ae0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
7af0: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
7b00: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
7b10: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
7b20: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
7b30: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
7b40: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
7b50: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
7b60: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
7b70: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
7b80: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
7b90: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
7ba0: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
7bb0: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
7bc0: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
7bd0: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
7be0: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
7bf0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
7c00: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
7c10: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
7c20: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
7c30: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
7c40: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
7c50: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
7c60: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
7c70: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
7c80: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
7c90: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
7ca0: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
7cb0: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
7cc0: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
7cd0: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
7ce0: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
7cf0: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
7d00: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
7d10: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
7d20: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
7d30: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
7d40: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
7d50: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
7d60: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
7d70: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
7d80: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
7d90: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
7da0: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
7db0: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
7dc0: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
7dd0: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
7de0: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
7df0: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
7e00: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
7e10: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
7e20: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51  wn use..** A [SQ
7e30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
7e40: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
7e50: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
7e60: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
7e70: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
7e80: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
7e90: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
7ea0: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
7eb0: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
7ec0: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
7ed0: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
7ee0: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
7ef0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
7f00: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
7f10: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
7f20: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
7f30: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
7f40: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
7f50: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
7f60: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
7f70: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
7f80: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
7f90: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
7fa0: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
7fb0: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
7fc0: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
7fd0: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
7fe0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
7ff0: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
8000: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
8010: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
8020: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
8030: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
8040: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
8050: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
8060: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
8070: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
8080: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
8090: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
80a0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
80b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
80c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
80d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
80e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
80f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
8100: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8110: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
8120: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8130: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
8140: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8150: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
8160: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
8170: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
8180: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
8190: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
81a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
81b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
81c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
81d0: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
81e0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
81f0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
8200: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
8210: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
8220: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
8230: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
8240: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
8250: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
8260: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8270: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8280: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
8290: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
82a0: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
82b0: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
82c0: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
82d0: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
82e0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
82f0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
8300: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
8310: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
8320: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
8330: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
8340: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
8350: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8360: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
8370: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
8380: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
8390: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
83a0: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
83b0: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
83c0: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
83d0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
83e0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
83f0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
8400: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
8410: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
8420: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
8430: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
8440: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
8450: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
8460: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
8470: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
8480: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
8490: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
84a0: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
84b0: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
84c0: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
84d0: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
84e0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
84f0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
8500: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
8510: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
8520: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
8530: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
8540: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
8550: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
8560: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
8570: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
8580: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
8590: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
85a0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
85b0: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
85c0: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
85d0: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
85e0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
85f0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
8600: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
8610: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8620: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8630: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
8640: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
8650: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
8660: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
8670: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
8680: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
8690: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
86a0: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
86b0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
86c0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
86d0: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
86e0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
86f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
8700: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
8710: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
8720: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8730: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
8740: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
8750: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
8760: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
8770: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
8780: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
8790: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
87a0: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
87b0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
87c0: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
87d0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
87e0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
87f0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
8800: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
8810: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
8820: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
8830: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
8840: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
8850: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
8860: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
8870: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
8880: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
8890: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
88a0: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
88b0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
88c0: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
88d0: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
88e0: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
88f0: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
8900: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
8910: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
8920: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
8930: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
8940: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
8950: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
8960: 6e 20 32 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  n 2 */.  int (*x
8970: 46 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  Fetch)(sqlite3_f
8980: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
8990: 74 36 34 20 69 4f 66 73 74 2c 20 69 6e 74 20 69  t64 iOfst, int i
89a0: 41 6d 74 2c 20 76 6f 69 64 20 2a 2a 70 70 29 3b  Amt, void **pp);
89b0: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 66 65 74 63  .  int (*xUnfetc
89c0: 68 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  h)(sqlite3_file*
89d0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
89e0: 69 4f 66 73 74 2c 20 76 6f 69 64 20 2a 70 29 3b  iOfst, void *p);
89f0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8a00: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8a10: 72 20 76 65 72 73 69 6f 6e 20 33 20 2a 2f 0a 20  r version 3 */. 
8a20: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
8a30: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
8a40: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
8a50: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
8a60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
8a70: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
8a80: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a  rol Opcodes.**.*
8a90: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
8aa0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
8ab0: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
8ac0: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
8ad0: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
8ae0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
8af0: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
8b00: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
8b10: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
8b20: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
8b30: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8b40: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
8b50: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
8b60: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
8b70: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
8b80: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
8b90: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
8ba0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
8bb0: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
8bc0: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
8bd0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
8be0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
8bf0: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
8c00: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
8c10: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
8c20: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
8c30: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
8c40: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
8c50: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
8c60: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
8c70: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
8c80: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
8c90: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
8ca0: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  ing and only nee
8cb0: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
8cc0: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
8cd0: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65  EST.** is define
8ce0: 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  d..** <ul>.** <l
8cf0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8d00: 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20  _SIZE_HINT]].** 
8d10: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8d20: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63  L_SIZE_HINT] opc
8d30: 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53  ode is used by S
8d40: 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68  QLite to give th
8d50: 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61  e VFS.** layer a
8d60: 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72   hint of how lar
8d70: 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
8d80: 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74  file will grow t
8d90: 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a  o be during the.
8da0: 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  ** current trans
8db0: 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69  action.  This hi
8dc0: 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e  nt is not guaran
8dd0: 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72  teed to be accur
8de0: 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73  ate but it.** is
8df0: 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54   often close.  T
8e00: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46  he underlying VF
8e10: 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74  S might choose t
8e20: 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61  o preallocate da
8e30: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73  tabase.** file s
8e40: 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68  pace based on th
8e50: 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72  is hint in order
8e60: 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20   to help writes 
8e70: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
8e80: 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74  ** file run fast
8e90: 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  er..**.** <li>[[
8ea0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
8eb0: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
8ec0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
8ed0: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
8ee0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
8ef0: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
8f00: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
8f10: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
8f20: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
8f30: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
8f40: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
8f50: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
8f60: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
8f70: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
8f80: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
8f90: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
8fa0: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
8fb0: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
8fc0: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
8fd0: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
8fe0: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
8ff0: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
9000: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
9010: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
9020: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
9030: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
9040: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
9050: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
9060: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
9070: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
9080: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
9090: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
90a0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
90b0: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
90c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
90d0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
90e0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
90f0: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
9100: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
9110: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
9120: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
9130: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
9140: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
9150: 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71  on.  See the [sq
9160: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
9170: 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74  ol()] documentat
9180: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  ion for.** addit
9190: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
91a0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
91b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
91c0: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28  _OMITTED]].** ^(
91d0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
91e0: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20  L_SYNC_OMITTED] 
91f0: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
9200: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
9210: 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  y.** SQLite and 
9220: 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65  sent to all VFSe
9230: 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20  s in place of a 
9240: 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e  call to the xSyn
9250: 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e  c method.** when
9260: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
9270: 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52  nnection has [PR
9280: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
9290: 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a  ] set to OFF.)^.
92a0: 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69  ** Some speciali
92b0: 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74  zed VFSes need t
92c0: 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72  his signal in or
92d0: 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63  der to operate c
92e0: 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e  orrectly.** when
92f0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
9300: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79  nous | PRAGMA sy
9310: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69  nchronous=OFF] i
9320: 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20  s set, but most 
9330: 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74  .** VFSes do not
9340: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9350: 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c  l and should sil
9360: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
9370: 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70  s opcode..** App
9380: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
9390: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74   not call [sqlit
93a0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
93b0: 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20  )] with this.** 
93c0: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
93d0: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
93e0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
93f0: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9400: 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f  VFSes.** that do
9410: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
9420: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9430: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
9440: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
9450: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
9460: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
9470: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
9480: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
9490: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
94a0: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
94b0: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
94c0: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
94d0: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
94e0: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
94f0: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
9500: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
9510: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
9520: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
9530: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
9540: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
9550: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
9560: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
9570: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
9580: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
9590: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
95a0: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
95b0: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
95c0: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
95d0: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
95e0: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
95f0: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
9600: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
9610: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
9620: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
9630: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
9640: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
9650: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
9660: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
9670: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
9680: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
9690: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
96a0: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
96b0: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
96c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
96d0: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
96e0: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
96f0: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
9700: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
9710: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
9720: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
9730: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
9740: 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74  er i the new ret
9750: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65  ry count and the
9760: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67   second.** integ
9770: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e  er is the delay.
9780: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65    If either inte
9790: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ger is negative,
97a0: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e   then the settin
97b0: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  g.** is not chan
97c0: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20  ged but instead 
97d0: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
97e0: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  of that setting 
97f0: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e  is written.** in
9800: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74  to the array ent
9810: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65  ry, allowing the
9820: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73   current retry s
9830: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a  ettings to be.**
9840: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
9850: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61  The zDbName para
9860: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64  meter is ignored
9870: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9880: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
9890: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65  ST_WAL]].** ^The
98a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
98b0: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f  ERSIST_WAL] opco
98c0: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
98d0: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
98e0: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41  * persistent [WA
98f0: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20  L | Write Ahead 
9900: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42  Log] setting.  B
9910: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61  y default, the a
9920: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74  uxiliary.** writ
9930: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20  e ahead log and 
9940: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
9950: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61  les used for tra
9960: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
9970: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69  .** are automati
9980: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68  cally deleted wh
9990: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f  en the latest co
99a0: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
99b0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73  database.** clos
99c0: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72  es.  Setting per
99d0: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
99e0: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69   causes those fi
99f0: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61  les to persist a
9a00: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20  fter.** close.  
9a10: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66  Persisting the f
9a20: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77  iles is useful w
9a30: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73  hen other proces
9a40: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a  ses that do not.
9a50: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65  ** have write pe
9a60: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20  rmission on the 
9a70: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
9a80: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
9a90: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74  e file want.** t
9aa0: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62  o read the datab
9ab0: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65  ase file, as the
9ac0: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20   WAL and shared 
9ad0: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73  memory files mus
9ae0: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72  t exist.** in or
9af0: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  der for the data
9b00: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61  base to be reada
9b10: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68  ble.  The fourth
9b20: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
9b30: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9b40: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
9b50: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
9b60: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
9b70: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
9b80: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
9b90: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72  0 to disable per
9ba0: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
9bb0: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
9bc0: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41  persistent.** WA
9bd0: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  L mode.  If the 
9be0: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
9bf0: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
9c00: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
9c10: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65  urrent.** WAL pe
9c20: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e  rsistence settin
9c30: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
9c40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
9c50: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
9c60: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
9c70: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
9c80: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  E_OVERWRITE] opc
9c90: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
9ca0: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
9cb0: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70  ** persistent "p
9cc0: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69  owersafe-overwri
9cd0: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65  te" or "PSOW" se
9ce0: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57  tting.  The PSOW
9cf0: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65   setting.** dete
9d00: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49  rmines the [SQLI
9d10: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
9d20: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69  FE_OVERWRITE] bi
9d30: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76  t of the.** xDev
9d40: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
9d50: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20  cs methods. The 
9d60: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
9d70: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
9d80: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
9d90: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
9da0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
9db0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
9dc0: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
9dd0: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
9de0: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  le zero-damage m
9df0: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
9e00: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a  le zero-damage.*
9e10: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  * mode.  If the 
9e20: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
9e30: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
9e40: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
9e50: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64  urrent.** zero-d
9e60: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69  amage mode setti
9e70: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
9e80: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
9e90: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
9ea0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
9eb0: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9ec0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
9ed0: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
9ee0: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
9ef0: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
9f00: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
9f10: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
9f20: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
9f30: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
9f40: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
9f50: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
9f60: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
9f70: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
9f80: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
9f90: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
9fa0: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
9fb0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9fc0: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20  TL_VFSNAME]].** 
9fd0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
9fe0: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
9ff0: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
a000: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
a010: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
a020: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
a030: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
a040: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
a050: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
a060: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
a070: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
a080: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
a090: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
a0a0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
a0b0: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
a0c0: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
a0d0: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
a0e0: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
a0f0: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
a100: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
a110: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
a120: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
a130: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
a140: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
a150: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
a160: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
a170: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
a180: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
a190: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
a1a0: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
a1b0: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
a1c0: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
a1d0: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
a1e0: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
a1f0: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
a200: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
a210: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
a220: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
a230: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
a240: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
a250: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
a260: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
a270: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  e only..**.** <l
a280: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
a290: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
a2a0: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
a2b0: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
a2c0: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
a2d0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a2e0: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
a2f0: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
a300: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
a310: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
a320: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
a330: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
a340: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
a350: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
a360: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
a370: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
a380: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a390: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
a3a0: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
a3b0: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
a3c0: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
a3d0: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
a3e0: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
a3f0: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
a400: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
a410: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
a420: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
a430: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
a440: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
a450: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
a460: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
a470: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
a480: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
a490: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
a4a0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
a4b0: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
a4c0: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
a4d0: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
a4e0: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
a4f0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
a500: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
a510: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
a520: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
a530: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
a540: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
a550: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
a560: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
a570: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
a580: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
a590: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
a5a0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
a5b0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a5c0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a5d0: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
a5e0: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
a5f0: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
a600: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
a610: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
a620: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a630: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
a640: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
a650: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
a660: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
a670: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
a680: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
a690: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
a6a0: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
a6b0: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
a6c0: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
a6d0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ent.  ^If the [S
a6e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a6f0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a700: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
a710: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65  result code othe
a720: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
a730: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f  K] or [SQLITE_NO
a740: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65  TFOUND], that me
a750: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ans.** that the 
a760: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  VFS encountered 
a770: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68  an error while h
a780: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41  andling the [PRA
a790: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  GMA] and the.** 
a7a0: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74  compilation of t
a7b0: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20  he PRAGMA fails 
a7c0: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
a7d0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
a7e0: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
a7f0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72  le control occur
a800: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69  s at the beginni
a810: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61  ng of pragma sta
a820: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20  tement analysis 
a830: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20  and so.** it is 
a840: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65  able to override
a850: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d   built-in [PRAGM
a860: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  A] statements..*
a870: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
a880: 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44  E_FCNTL_BUSYHAND
a890: 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  LER]].** ^The [S
a8a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
a8b0: 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65  HANDLER].** file
a8c0: 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20  -control may be 
a8d0: 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74  invoked by SQLit
a8e0: 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  e on the databas
a8f0: 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a  e file handle.**
a900: 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72 20 69   shortly after i
a910: 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f  t is opened in o
a920: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
a930: 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77 69 74  a custom VFS wit
a940: 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74  h access.** to t
a950: 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62  he connections b
a960: 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy-handler call
a970: 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75 6d 65  back. The argume
a980: 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20 28 76  nt is of type (v
a990: 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20  oid **).** - an 
a9a0: 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28 76 6f  array of two (vo
a9b0: 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20 54 68  id *) values. Th
a9c0: 65 20 66 69 72 73 74 20 28 76 6f 69 64 20 2a 29  e first (void *)
a9d0: 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73   actually points
a9e0: 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  .** to a functio
a9f0: 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74 20 28  n of type (int (
aa00: 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20  *)(void *)). In 
aa10: 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20  order to invoke 
aa20: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a  the connections.
aa30: 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c  ** busy-handler,
aa40: 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 73   this function s
aa50: 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64  hould be invoked
aa60: 20 77 69 74 68 20 74 68 65 20 73 65 63 6f 6e 64   with the second
aa70: 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20   (void *) in.** 
aa80: 74 68 65 20 61 72 72 61 79 20 61 73 20 74 68 65  the array as the
aa90: 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20   only argument. 
aaa0: 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 6e 6f  If it returns no
aab0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
aac0: 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68   operation.** sh
aad0: 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65 64 2e  ould be retried.
aae0: 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20 7a   If it returns z
aaf0: 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f 6d 20  ero, the custom 
ab00: 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61 6e 64  VFS should aband
ab10: 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  on the.** curren
ab20: 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  t operation..**.
ab30: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
ab40: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
ab50: 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61  ME]].** ^Applica
ab60: 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20  tion can invoke 
ab70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
ab80: 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20  L_TEMPFILENAME] 
ab90: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
aba0: 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65 20 67  to have SQLite g
abb0: 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d  enerate a.** tem
abc0: 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 20  porary filename 
abd0: 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 61  using the same a
abe0: 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20 69 73  lgorithm that is
abf0: 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e   followed to gen
ac00: 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61  erate.** tempora
ac10: 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72  ry filenames for
ac20: 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61 6e 64   TEMP tables and
ac30: 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 20   other internal 
ac40: 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72  uses.  The.** ar
ac50: 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
ac60: 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63 68 20   a char** which 
ac70: 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64 20 77  will be filled w
ac80: 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ith the filename
ac90: 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  .** written into
aca0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
acb0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
acc0: 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65 20 63  alloc()].  The c
acd0: 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20  aller should.** 
ace0: 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f  invoke [sqlite3_
acf0: 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65 20 72  free()] on the r
ad00: 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64 20 61  esult to avoid a
ad10: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a   memory leak..**
ad20: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
ad30: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
ad40: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
ad50: 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
ad60: 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  E] file control 
ad70: 69 73 20 75 73 65 64 20 74 6f 20 71 75 65 72 79  is used to query
ad80: 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d   or set the.** m
ad90: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
ada0: 20 62 79 74 65 73 20 74 68 61 74 20 77 69 6c 6c   bytes that will
adb0: 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d 65 6d   be used for mem
adc0: 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a  ory-mapped I/O..
add0: 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  ** The argument 
ade0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
adf0: 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70 65 20  a value of type 
ae00: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 74 68  sqlite3_int64 th
ae10: 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64 76 69  at.** is an advi
ae20: 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  sory maximum num
ae30: 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
ae40: 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f  the file to memo
ae50: 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20  ry map.  The.** 
ae60: 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65 72 77  pointer is overw
ae70: 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20  ritten with the 
ae80: 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68 65 20  old value.  The 
ae90: 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 68 61  limit is not cha
aea0: 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65 20 76  nged if.** the v
aeb0: 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20  alue originally 
aec0: 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20 6e 65  pointed to is ne
aed0: 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f 20 74  gative, and so t
aee0: 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d 69 74  he current limit
aef0: 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75 65 72   .** can be quer
af00: 69 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 69  ied by passing i
af10: 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  n a pointer to a
af20: 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72   negative number
af30: 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d  .  This.** file-
af40: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
af50: 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d  internally to im
af60: 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20  plement [PRAGMA 
af70: 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a  mmap_size]..**.*
af80: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
af90: 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20  CNTL_TRACE]].** 
afa0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
afb0: 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20 63 6f  L_TRACE] file co
afc0: 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73 20 61  ntrol provides a
afd0: 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74  dvisory informat
afe0: 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46  ion.** to the VF
aff0: 53 20 61 62 6f 75 74 20 77 68 61 74 20 74 68 65  S about what the
b000: 20 68 69 67 68 65 72 20 6c 61 79 65 72 73 20 6f   higher layers o
b010: 66 20 74 68 65 20 53 51 4c 69 74 65 20 73 74 61  f the SQLite sta
b020: 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a  ck are doing..**
b030: 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72   This file contr
b040: 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20 73 6f  ol is used by so
b050: 6d 65 20 56 46 53 20 61 63 74 69 76 69 74 79 20  me VFS activity 
b060: 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e  tracing [shims].
b070: 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e 74  .** The argument
b080: 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   is a zero-termi
b090: 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20 20 48  nated string.  H
b0a0: 69 67 68 65 72 20 6c 61 79 65 72 73 20 69 6e 20  igher layers in 
b0b0: 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74  the.** SQLite st
b0c0: 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61 74 65  ack may generate
b0d0: 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20 74 68   instances of th
b0e0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b0f0: 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  if.** the [SQLIT
b100: 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43  E_USE_FCNTL_TRAC
b110: 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  E] compile-time 
b120: 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
b130: 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  d..**.** </ul>.*
b140: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
b150: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
b160: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
b170: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b180: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
b190: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a  E             2.
b1a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
b1b0: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
b1c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23               3.#
b1d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41  define SQLITE_LA
b1e0: 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20  ST_ERRNO        
b1f0: 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64              4.#d
b200: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b210: 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20  TL_SIZE_HINT    
b220: 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65             5.#de
b230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b240: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20  L_CHUNK_SIZE    
b250: 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
b260: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b270: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20  _FILE_POINTER   
b280: 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
b290: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b2a0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20  SYNC_OMITTED    
b2b0: 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e          8.#defin
b2c0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57  e SQLITE_FCNTL_W
b2d0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20  IN32_AV_RETRY   
b2e0: 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65         9.#define
b2f0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45   SQLITE_FCNTL_PE
b300: 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20  RSIST_WAL       
b310: 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20       10.#define 
b320: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
b330: 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20  RWRITE          
b340: 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53      11.#define S
b350: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e  QLITE_FCNTL_VFSN
b360: 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20  AME             
b370: 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51     12.#define SQ
b380: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
b390: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20  SAFE_OVERWRITE  
b3a0: 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c    13.#define SQL
b3b0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
b3c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b3d0: 20 31 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   14.#define SQLI
b3e0: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
b3f0: 44 4c 45 52 20 20 20 20 20 20 20 20 20 20 20 20  DLER            
b400: 31 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  15.#define SQLIT
b410: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
b420: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 31  NAME           1
b430: 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  6.#define SQLITE
b440: 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45  _FCNTL_MMAP_SIZE
b450: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 38                18
b460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b470: 46 43 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20  FCNTL_TRACE     
b480: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39 0a               19.
b490: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b4a0: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
b4b0: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
b4c0: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
b4d0: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
b4e0: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
b4f0: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
b500: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
b510: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
b520: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
b530: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
b540: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
b550: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
b560: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
b570: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
b580: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
b590: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
b5a0: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
b5b0: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
b5c0: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
b5d0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
b5e0: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
b5f0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
b600: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
b610: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
b620: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
b630: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
b640: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
b650: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
b660: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
b670: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
b680: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
b690: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
b6a0: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
b6b0: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
b6c0: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
b6d0: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
b6e0: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
b6f0: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
b700: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
b710: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
b720: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
b730: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
b740: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
b750: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
b760: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
b770: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
b780: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
b790: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
b7a0: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
b7b0: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
b7c0: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
b7d0: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
b7e0: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
b7f0: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
b800: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
b810: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
b820: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
b830: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
b840: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
b850: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
b860: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
b870: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
b880: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
b890: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
b8a0: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
b8b0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
b8c0: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
b8d0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
b8e0: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
b8f0: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
b900: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
b910: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
b920: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
b930: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
b940: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
b950: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
b960: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
b970: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
b980: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
b990: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
b9a0: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
b9b0: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
b9c0: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
b9d0: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
b9e0: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
b9f0: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
ba00: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
ba10: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
ba20: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
ba30: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
ba40: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
ba50: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
ba60: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
ba70: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
ba80: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
ba90: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
baa0: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
bab0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
bac0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
bad0: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
bae0: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
baf0: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
bb00: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
bb10: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
bb20: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
bb30: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
bb40: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
bb50: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
bb60: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
bb70: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
bb80: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
bb90: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
bba0: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
bbb0: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
bbc0: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
bbd0: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
bbe0: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
bbf0: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
bc00: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
bc10: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
bc20: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
bc30: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
bc40: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
bc50: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
bc60: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
bc70: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
bc80: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
bc90: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
bca0: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
bcb0: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
bcc0: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
bcd0: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
bce0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
bcf0: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
bd00: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
bd10: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
bd20: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
bd30: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
bd40: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
bd50: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
bd60: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
bd70: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
bd80: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
bd90: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
bda0: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
bdb0: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
bdc0: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
bdd0: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
bde0: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
bdf0: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
be00: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
be10: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
be20: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
be30: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
be40: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
be50: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
be60: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
be70: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
be80: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
be90: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
bea0: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
beb0: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
bec0: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
bed0: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
bee0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
bef0: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
bf00: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
bf10: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
bf20: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
bf30: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
bf40: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
bf50: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
bf60: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
bf70: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
bf80: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
bf90: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
bfa0: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
bfb0: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
bfc0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
bfd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
bfe0: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
bff0: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
c000: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
c010: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
c020: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
c030: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
c040: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
c050: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
c060: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
c070: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
c080: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
c090: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
c0a0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
c0b0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
c0c0: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
c0d0: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
c0e0: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
c0f0: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
c100: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
c110: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
c120: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
c130: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
c140: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
c150: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
c160: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
c170: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
c180: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
c190: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
c1a0: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
c1b0: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
c1c0: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
c1d0: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
c1e0: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
c1f0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c200: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
c210: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c220: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
c230: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
c240: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
c250: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
c260: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
c270: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
c280: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c290: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
c2a0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c2b0: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
c2c0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c2d0: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
c2e0: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
c2f0: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
c300: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
c310: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
c320: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
c330: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
c340: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
c350: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
c360: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
c370: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
c380: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
c390: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
c3a0: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
c3b0: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
c3c0: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
c3d0: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
c3e0: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
c3f0: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
c400: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
c410: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
c420: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
c430: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
c440: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
c450: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
c460: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
c470: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
c480: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
c490: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
c4a0: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
c4b0: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
c4c0: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
c4d0: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
c4e0: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
c4f0: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
c500: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
c510: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
c520: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
c530: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
c540: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
c550: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
c560: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
c570: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
c580: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
c590: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
c5a0: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
c5b0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
c5c0: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
c5d0: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
c5e0: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
c5f0: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
c600: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
c610: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
c620: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
c630: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
c640: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
c650: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
c660: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
c670: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
c680: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
c690: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
c6a0: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
c6b0: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
c6c0: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
c6d0: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
c6e0: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
c6f0: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
c700: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
c710: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
c720: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
c730: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
c740: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
c750: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
c760: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
c770: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
c780: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
c790: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
c7a0: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
c7b0: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
c7c0: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
c7d0: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
c7e0: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
c7f0: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
c800: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
c810: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
c820: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
c830: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
c840: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
c850: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
c860: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
c870: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
c880: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
c890: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
c8a0: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
c8b0: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
c8c0: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
c8d0: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
c8e0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
c8f0: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
c900: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
c910: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
c920: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
c930: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
c940: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
c950: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
c960: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
c970: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
c980: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
c990: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
c9a0: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
c9b0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
c9c0: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
c9d0: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
c9e0: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
c9f0: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
ca00: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
ca10: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
ca20: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
ca30: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
ca40: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
ca50: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
ca60: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
ca70: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
ca80: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
ca90: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
caa0: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
cab0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
cac0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
cad0: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
cae0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
caf0: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
cb00: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
cb10: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
cb20: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
cb30: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
cb40: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
cb50: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
cb60: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
cb70: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
cb80: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
cb90: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
cba0: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
cbb0: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
cbc0: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
cbd0: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
cbe0: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
cbf0: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
cc00: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
cc10: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
cc20: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
cc30: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
cc40: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
cc50: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
cc60: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
cc70: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
cc80: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
cc90: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
cca0: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
ccb0: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
ccc0: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
ccd0: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
cce0: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
ccf0: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
cd00: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
cd10: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
cd20: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
cd30: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
cd40: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
cd50: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
cd60: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
cd70: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
cd80: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
cd90: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
cda0: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
cdb0: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
cdc0: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
cdd0: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
cde0: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
cdf0: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
ce00: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
ce10: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
ce20: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
ce30: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
ce40: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
ce50: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
ce60: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
ce70: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
ce80: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
ce90: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
cea0: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
ceb0: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
cec0: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
ced0: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
cee0: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
cef0: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
cf00: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
cf10: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
cf20: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
cf30: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
cf40: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
cf50: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
cf60: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
cf70: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
cf80: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
cf90: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
cfa0: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
cfb0: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
cfc0: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
cfd0: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
cfe0: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
cff0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d000: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
d010: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
d020: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
d030: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
d040: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
d050: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
d060: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
d070: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
d080: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
d090: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
d0a0: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d0b0: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
d0c0: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
d0d0: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
d0e0: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
d0f0: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
d100: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
d110: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
d120: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
d130: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
d140: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
d150: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
d160: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
d170: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
d180: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
d190: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
d1a0: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
d1b0: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
d1c0: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
d1d0: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
d1e0: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
d1f0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
d200: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
d210: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
d220: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
d230: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
d240: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
d250: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
d260: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
d270: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
d280: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
d290: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
d2a0: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
d2b0: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
d2c0: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
d2d0: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
d2e0: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
d2f0: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
d300: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
d310: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
d320: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
d330: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
d340: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
d350: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
d360: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
d370: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
d380: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
d390: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
d3a0: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
d3b0: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
d3c0: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
d3d0: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
d3e0: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
d3f0: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
d400: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
d410: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
d420: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
d430: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
d440: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
d450: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
d460: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
d470: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
d480: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
d490: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
d4a0: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
d4b0: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
d4c0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
d4d0: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
d4e0: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
d4f0: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
d500: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
d510: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
d520: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
d530: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
d540: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
d550: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
d560: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
d570: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
d580: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
d590: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
d5a0: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
d5b0: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
d5c0: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
d5d0: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
d5e0: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
d5f0: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
d600: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
d610: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
d620: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
d630: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
d640: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
d650: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
d660: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
d670: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
d680: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
d690: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
d6a0: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
d6b0: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
d6c0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
d6d0: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
d6e0: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
d6f0: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
d700: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
d710: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
d720: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
d730: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d740: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
d750: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
d760: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
d770: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
d780: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
d790: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
d7a0: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
d7b0: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
d7c0: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
d7d0: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
d7e0: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
d7f0: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
d800: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
d810: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
d820: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
d830: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
d840: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
d850: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
d860: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
d870: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
d880: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
d890: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
d8a0: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
d8b0: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
d8c0: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
d8d0: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
d8e0: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
d8f0: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
d900: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
d910: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
d920: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
d930: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
d940: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
d950: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
d960: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
d970: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
d980: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
d990: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
d9a0: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
d9b0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
d9c0: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
d9d0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
d9e0: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
d9f0: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
da00: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
da10: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
da20: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
da30: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
da40: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
da50: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
da60: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
da70: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
da80: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
da90: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
daa0: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
dab0: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
dac0: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
dad0: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
dae0: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
daf0: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
db00: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
db10: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
db20: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
db30: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
db40: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
db50: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
db60: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
db70: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
db80: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
db90: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
dba0: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
dbb0: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
dbc0: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
dbd0: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
dbe0: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
dbf0: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
dc00: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
dc10: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
dc20: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
dc30: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
dc40: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
dc50: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
dc60: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
dc70: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
dc80: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
dc90: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
dca0: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
dcb0: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
dcc0: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
dcd0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
dce0: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
dcf0: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
dd00: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
dd10: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
dd20: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
dd30: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
dd40: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
dd50: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
dd60: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
dd70: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
dd80: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
dd90: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
dda0: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
ddb0: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
ddc0: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
ddd0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
dde0: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
ddf0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
de00: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
de10: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
de20: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
de30: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
de40: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
de50: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
de60: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
de70: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
de80: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
de90: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
dea0: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
deb0: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
dec0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
ded0: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
dee0: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
def0: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
df00: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
df10: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
df20: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
df30: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
df40: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
df50: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
df60: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
df70: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
df80: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
df90: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
dfa0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
dfb0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
dfc0: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
dfd0: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
dfe0: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
dff0: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
e000: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
e010: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
e020: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
e030: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
e040: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
e050: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
e060: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
e070: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
e080: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
e090: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
e0a0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e0b0: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
e0c0: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
e0d0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
e0e0: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
e0f0: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
e100: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
e110: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
e120: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
e130: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
e140: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
e150: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e160: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
e170: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
e180: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
e190: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
e1a0: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
e1b0: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
e1c0: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
e1d0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
e1e0: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
e1f0: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e200: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
e210: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
e220: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
e230: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
e240: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
e250: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e260: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
e270: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
e280: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
e290: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
e2a0: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
e2b0: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
e2c0: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
e2d0: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
e2e0: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
e2f0: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68   was given no th
e300: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
e310: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
e320: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
e330: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
e340: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
e350: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
e360: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
e370: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
e380: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
e390: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
e3a0: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
e3b0: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
e3c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e3d0: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
e3e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e3f0: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
e400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e410: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
e420: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
e430: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
e440: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
e450: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
e460: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
e470: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
e480: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
e490: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
e4a0: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
e4b0: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
e4c0: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
e4d0: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
e4e0: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
e4f0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
e500: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
e510: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
e520: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
e530: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
e540: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
e550: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
e560: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
e570: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
e580: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
e590: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
e5a0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
e5b0: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
e5c0: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
e5d0: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
e5e0: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
e5f0: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
e600: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
e610: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
e620: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
e630: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
e640: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
e650: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
e660: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
e670: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
e680: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
e690: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
e6a0: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
e6b0: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
e6c0: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
e6d0: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
e6e0: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
e6f0: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
e700: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
e710: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
e720: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
e730: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
e740: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
e750: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
e760: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
e770: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e780: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
e790: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
e7a0: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
e7b0: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
e7c0: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
e7d0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
e7e0: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
e7f0: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
e800: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
e810: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
e820: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
e830: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
e840: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
e850: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
e860: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
e870: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
e880: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
e890: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
e8a0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
e8b0: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
e8c0: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
e8d0: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
e8e0: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
e8f0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e900: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
e910: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
e920: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
e930: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
e940: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
e950: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
e960: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
e970: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
e980: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
e990: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
e9a0: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
e9b0: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
e9c0: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
e9d0: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
e9e0: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
e9f0: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
ea00: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
ea10: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
ea20: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
ea30: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
ea40: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
ea50: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
ea60: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
ea70: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
ea80: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
ea90: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
eaa0: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
eab0: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
eac0: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
ead0: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
eae0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
eaf0: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
eb00: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
eb10: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
eb20: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
eb30: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
eb40: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
eb50: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
eb60: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
eb70: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
eb80: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
eb90: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
eba0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
ebb0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
ebc0: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
ebd0: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
ebe0: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
ebf0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
ec00: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
ec10: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
ec20: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
ec30: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
ec40: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
ec50: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
ec60: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
ec70: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
ec80: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
ec90: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
eca0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
ecb0: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
ecc0: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
ecd0: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
ece0: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
ecf0: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
ed00: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
ed10: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
ed20: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
ed30: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
ed40: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
ed50: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
ed60: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
ed70: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
ed80: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
ed90: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
eda0: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
edb0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
edc0: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
edd0: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
ede0: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
edf0: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
ee00: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
ee10: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
ee20: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
ee30: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
ee40: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
ee50: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
ee60: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
ee70: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
ee80: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
ee90: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
eea0: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
eeb0: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
eec0: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
eed0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
eee0: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
eef0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
ef00: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
ef10: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
ef20: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
ef30: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
ef40: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
ef50: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
ef60: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
ef70: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
ef80: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
ef90: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
efa0: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
efb0: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
efc0: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
efd0: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
efe0: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
eff0: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
f000: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
f010: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
f020: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
f030: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
f040: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
f050: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
f060: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
f070: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
f080: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
f090: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
f0a0: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
f0b0: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
f0c0: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
f0d0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
f0e0: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
f0f0: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
f100: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
f110: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
f120: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
f130: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
f140: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
f150: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
f160: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
f170: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
f180: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
f190: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
f1a0: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
f1b0: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
f1c0: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
f1d0: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
f1e0: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
f1f0: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
f200: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
f210: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
f220: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
f230: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
f240: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
f250: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
f260: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
f270: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
f280: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
f290: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
f2a0: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
f2b0: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
f2c0: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
f2d0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
f2e0: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f2f0: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
f300: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
f310: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
f320: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
f330: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
f340: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
f350: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f360: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
f370: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f380: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
f390: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
f3a0: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
f3b0: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
f3c0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f3d0: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
f3e0: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
f3f0: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
f400: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
f410: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
f420: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
f430: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
f440: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
f450: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
f460: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
f470: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
f480: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
f490: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
f4a0: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
f4b0: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
f4c0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f4d0: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
f4e0: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
f4f0: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
f500: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
f510: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
f520: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
f530: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f540: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
f550: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
f560: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
f570: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
f580: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
f590: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
f5a0: 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
f5b0: 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49  lize(void);.SQLI
f5c0: 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
f5d0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
f5e0: 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
f5f0: 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
f600: 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  t(void);.SQLITE_
f610: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
f620: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
f630: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
f640: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
f650: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
f660: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
f670: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
f680: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
f690: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
f6a0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
f6b0: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
f6c0: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
f6d0: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
f6e0: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
f6f0: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
f700: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
f710: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
f720: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
f730: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
f740: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
f750: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
f760: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
f770: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
f780: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
f790: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
f7a0: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
f7b0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
f7c0: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
f7d0: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
f7e0: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
f7f0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
f800: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
f810: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
f820: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
f830: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
f840: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
f850: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
f860: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
f870: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
f880: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f890: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
f8a0: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
f8b0: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
f8c0: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
f8d0: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
f8e0: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
f8f0: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
f900: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f910: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
f920: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
f930: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
f940: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f950: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
f960: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
f970: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
f980: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
f990: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
f9a0: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
f9b0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f9c0: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
f9d0: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
f9e0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f9f0: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
fa00: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
fa10: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
fa20: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
fa30: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
fa40: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
fa50: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
fa60: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
fa70: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
fa80: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
fa90: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
faa0: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
fab0: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
fac0: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
fad0: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
fae0: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
faf0: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
fb00: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
fb10: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
fb20: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
fb30: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
fb40: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
fb50: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
fb60: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
fb70: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
fb80: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
fb90: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
fba0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
fbb0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
fbc0: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
fbd0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
fbe0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
fbf0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
fc00: 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
fc10: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
fc20: 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
fc30: 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
fc40: 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
fc50: 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
fc60: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
fc70: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
fc80: 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
fc90: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
fca0: 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
fcb0: 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
fcc0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
fcd0: 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
fce0: 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
fcf0: 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
fd00: 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
fd10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
fd20: 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
fd30: 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
fd40: 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
fd50: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
fd60: 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
fd70: 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
fd80: 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
fd90: 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
fda0: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
fdb0: 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
fdc0: 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
fdd0: 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
fde0: 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
fdf0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
fe00: 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
fe10: 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
fe20: 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
fe30: 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
fe40: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
fe50: 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
fe60: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
fe70: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
fe80: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
fe90: 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
fea0: 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
feb0: 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
fec0: 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
fed0: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f   int sqlite3_db_
fee0: 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
fef0: 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
ff00: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ff10: 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
ff20: 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
ff30: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
ff40: 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
ff50: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
ff60: 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
ff70: 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
ff80: 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
ff90: 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
ffa0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
ffb0: 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
ffc0: 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
ffd0: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
ffe0: 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
fff0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
10000 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
10010 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
10020 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
10030 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
10040 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
10050 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
10060 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
10070 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
10080 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
10090 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
100a0 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
100b0 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
100c0 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
100d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
100e0 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
100f0 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
10100 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
10110 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
10120 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
10130 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
10140 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10150 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
10160 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
10170 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
10180 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
10190 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
101a0 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
101b0 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
101c0 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
101d0 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
101e0 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
101f0 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
10200 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
10210 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
10220 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
10230 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
10240 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
10250 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
10260 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
10270 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
10280 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
10290 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
102a0 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
102b0 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
102c0 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
102d0 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
102e0 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
102f0 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
10300 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
10310 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
10320 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
10330 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
10340 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
10350 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
10360 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
10370 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
10380 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
10390 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
103a0 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
103b0 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
103c0 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
103d0 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
103e0 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
103f0 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
10400 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
10410 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
10420 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
10430 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
10440 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
10450 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
10460 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
10470 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
10480 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
10490 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
104a0 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
104b0 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
104c0 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
104d0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
104e0 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
104f0 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
10500 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
10510 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
10520 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
10530 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
10540 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
10550 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
10560 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
10570 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
10580 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
10590 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
105a0 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
105b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
105c0 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
105d0 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
105e0 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
105f0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
10600 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
10610 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
10620 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
10630 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
10640 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
10650 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
10660 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
10670 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
10680 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
10690 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
106a0 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
106b0 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
106c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
106d0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
106e0 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
106f0 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
10700 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
10710 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
10720 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
10730 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
10740 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
10750 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
10760 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
10770 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
10780 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65  llocator.  For e
10790 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69  xample,.** it mi
107a0 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79  ght allocate any
107b0 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73   require mutexes
107c0 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69   or initialize i
107d0 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20  nternal data.** 
107e0 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65  structures.  The
107f0 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
10800 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e  d is invoked (in
10810 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20  directly) by.** 
10820 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
10830 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20  n()] and should 
10840 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  deallocate any r
10850 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65  esources acquire
10860 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20  d.** by xInit.  
10870 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69  The pAppData poi
10880 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20  nter is used as 
10890 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74  the only paramet
108a0 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61  er to.** xInit a
108b0 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a  nd xShutdown..**
108c0 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73  .** SQLite holds
108d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
108e0 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52  EX_STATIC_MASTER
108f0 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20  ] mutex when it 
10900 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78  invokes.** the x
10910 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20  Init method, so 
10920 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
10930 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72   need not be thr
10940 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a  eadsafe.  The.**
10950 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f   xShutdown metho
10960 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64  d is only called
10970 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73   from [sqlite3_s
10980 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74  hutdown()] so it
10990 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65   does.** not nee
109a0 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61  d to be threadsa
109b0 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20  fe either.  For 
109c0 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64  all other method
109d0 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c  s, SQLite.** hol
109e0 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d  ds the [SQLITE_M
109f0 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d  UTEX_STATIC_MEM]
10a00 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61   mutex as long a
10a10 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  s the.** [SQLITE
10a20 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
10a30 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  S] configuration
10a40 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65   option is turne
10a50 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69  d on (which.** i
10a60 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29  t is by default)
10a70 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68   and so the meth
10a80 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69  ods are automati
10a90 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64  cally serialized
10aa0 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66  ..** However, if
10ab0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
10ac0 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69  MEMSTATUS] is di
10ad0 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65  sabled, then the
10ae0 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64   other.** method
10af0 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64  s must be thread
10b00 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b  safe or else mak
10b10 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61  e their own arra
10b20 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20  ngements for.** 
10b30 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a  serialization..*
10b40 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c  *.** SQLite will
10b50 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49   never invoke xI
10b60 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20  nit() more than 
10b70 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20  once without an 
10b80 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63  intervening.** c
10b90 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e  all to xShutdown
10ba0 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ()..*/.typedef s
10bb0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
10bc0 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  m_methods sqlite
10bd0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73  3_mem_methods;.s
10be0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65  truct sqlite3_me
10bf0 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f  m_methods {.  vo
10c00 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69  id *(*xMalloc)(i
10c10 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20  nt);         /* 
10c20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
10c30 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20  n function */.  
10c40 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f  void (*xFree)(vo
10c50 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f  id*);          /
10c60 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61  * Free a prior a
10c70 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76  llocation */.  v
10c80 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29  oid *(*xRealloc)
10c90 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a  (void*,int);  /*
10ca0 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63   Resize an alloc
10cb0 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
10cc0 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20  *xSize)(void*); 
10cd0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74            /* Ret
10ce0 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  urn the size of 
10cf0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
10d00 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75  .  int (*xRoundu
10d10 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  p)(int);        
10d20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65    /* Round up re
10d30 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c  quest size to al
10d40 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f  location size */
10d50 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28  .  int (*xInit)(
10d60 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
10d70 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20    /* Initialize 
10d80 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
10d90 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28  ator */.  void (
10da0 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64  *xShutdown)(void
10db0 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e  *);      /* Dein
10dc0 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d  itialize the mem
10dd0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f  ory allocator */
10de0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74  .  void *pAppDat
10df0 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  a;              
10e00 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f    /* Argument to
10e10 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68   xInit() and xSh
10e20 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a  utdown() */.};..
10e30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
10e40 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70  Configuration Op
10e50 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
10e60 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f  S: {configuratio
10e70 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20  n option}.**.** 
10e80 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
10e90 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
10ea0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
10eb0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
10ec0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
10ed0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69 72  assed as the fir
10ee0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
10ef0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  he [sqlite3_conf
10f00 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ig()] interface.
10f10 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69  .**.** New confi
10f20 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
10f30 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
10f40 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
10f50 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45   of SQLite..** E
10f60 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72  xisting configur
10f70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69  ation options mi
10f80 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e  ght be discontin
10f90 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ued.  Applicatio
10fa0 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65  ns.** should che
10fb0 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
10fc0 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  de from [sqlite3
10fd0 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61  _config()] to ma
10fe0 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20  ke sure that.** 
10ff0 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e  the call worked.
11000 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63    The [sqlite3_c
11010 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
11020 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61  ce will return a
11030 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  .** non-zero [er
11040 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64  ror code] if a d
11050 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75  iscontinued or u
11060 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69  nsupported confi
11070 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a  guration option.
11080 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a  ** is invoked..*
11090 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
110a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
110b0 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  GLETHREAD]] <dt>
110c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
110d0 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a  NGLETHREAD</dt>.
110e0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
110f0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
11100 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
11110 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
11120 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
11130 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67  ng mode] to Sing
11140 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  le-thread.  In o
11150 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
11160 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  isables.** all m
11170 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73  utexing and puts
11180 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d   SQLite into a m
11190 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61 6e  ode where it can
111a0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a   only be used.**
111b0 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72   by a single thr
111c0 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74  ead.   ^If SQLit
111d0 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
111e0 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
111f0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
11200 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
11210 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
11220 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
11230 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
11240 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  le to change the
11250 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11260 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75  ] from its defau
11270 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53  lt.** value of S
11280 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64  ingle-thread and
11290 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   so [sqlite3_con
112a0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
112b0 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  rn .** [SQLITE_E
112c0 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
112d0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
112e0 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
112f0 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  EAD.** configura
11300 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
11310 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11320 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11330 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  EAD]] <dt>SQLITE
11340 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
11350 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  EAD</dt>.** <dd>
11360 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
11370 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
11380 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
11390 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
113a0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
113b0 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61  ] to Multi-threa
113c0 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
113d0 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
113e0 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b  ** mutexing on [
113f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11400 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
11410 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
11420 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70  jects..** The ap
11430 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73  plication is res
11440 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72  ponsible for ser
11450 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20  ializing access 
11460 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  to.** [database 
11470 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64  connections] and
11480 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11490 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68  ments].  But oth
114a0 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72  er mutexes.** ar
114b0 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61  e enabled so tha
114c0 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65  t SQLite will be
114d0 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20   safe to use in 
114e0 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64  a multi-threaded
114f0 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20  .** environment 
11500 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77  as long as no tw
11510 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d 70  o threads attemp
11520 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d  t to use the sam
11530 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
11540 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68  onnection] at th
11550 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49  e same time.  ^I
11560 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
11570 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
11580 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
11590 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
115a0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
115b0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
115c0 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
115d0 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74   possible to set
115e0 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61   the Multi-threa
115f0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
11600 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
11610 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
11620 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
11630 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
11640 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
11650 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
11660 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72  ITHREAD configur
11670 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
11680 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
11690 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
116a0 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  ZED]] <dt>SQLITE
116b0 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
116c0 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
116d0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
116e0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
116f0 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
11700 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
11710 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11720 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20   to Serialized. 
11730 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
11740 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62  this option enab
11750 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
11760 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65  es including the
11770 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75   recursive.** mu
11780 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61  texes on [databa
11790 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
117a0 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
117b0 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e  tement] objects.
117c0 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65  .** In this mode
117d0 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20 64   (which is the d
117e0 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69  efault when SQLi
117f0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
11800 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54  ith.** [SQLITE_T
11810 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68  HREADSAFE=1]) th
11820 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
11830 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72   will itself ser
11840 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a  ialize access.**
11850 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f   to [database co
11860 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
11870 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
11880 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65  nts] so that the
11890 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
118a0 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20 74  is free to use t
118b0 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
118c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72  e connection] or
118d0 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72   the.** same [pr
118e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
118f0 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74  ] in different t
11900 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
11910 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20  me time..** ^If 
11920 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11930 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11940 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11950 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11960 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11970 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11980 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
11990 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
119a0 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74  he Serialized [t
119b0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61  hreading mode] a
119c0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  nd.** [sqlite3_c
119d0 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65  onfig()] will re
119e0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52  turn [SQLITE_ERR
119f0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11a00 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45  th the.** SQLITE
11a10 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a  _CONFIG_SERIALIZ
11a20 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ED configuration
11a30 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
11a40 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11a50 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  FIG_MALLOC]] <dt
11a60 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
11a70 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
11a80 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
11a90 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
11aa0 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
11ab0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
11ac0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
11ad0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
11ae0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
11af0 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d  ture.  The argum
11b00 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  ent specifies.**
11b10 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77   alternative low
11b20 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
11b30 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
11b40 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20  s to be used in 
11b50 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20  place of.** the 
11b60 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11b70 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  n routines built
11b80 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
11b90 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a  ^SQLite makes.**
11ba0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
11bb0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e   copy of the con
11bc0 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c  tent of the [sql
11bd0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
11be0 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62  ] structure.** b
11bf0 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74  efore the [sqlit
11c00 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c  e3_config()] cal
11c10 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a  l returns.</dd>.
11c20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11c30 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d  ONFIG_GETMALLOC]
11c40 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
11c50 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64  FIG_GETMALLOC</d
11c60 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
11c70 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
11c80 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
11c90 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
11ca0 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
11cb0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
11cc0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
11cd0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
11ce0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
11cf0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
11d00 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
11d10 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
11d20 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72  ly defined memor
11d30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
11d40 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73  tines.)^.** This
11d50 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75   option can be u
11d60 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20  sed to overload 
11d70 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  the default memo
11d80 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
11d90 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61   routines with a
11da0 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73 69   wrapper that si
11db0 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79  mulations memory
11dc0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
11dd0 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73  ure or.** tracks
11de0 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66   memory usage, f
11df0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64  or example. </dd
11e00 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
11e10 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
11e20 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  S]] <dt>SQLITE_C
11e30 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
11e40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
11e50 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
11e60 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
11e70 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74  of type int, int
11e80 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a  erpreted as a .*
11e90 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  * boolean, which
11ea0 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
11eb0 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74  bles the collect
11ec0 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ion of memory al
11ed0 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61  location .** sta
11ee0 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
11ef0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
11f00 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
11f10 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a   disabled, the .
11f20 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  ** following SQL
11f30 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
11f40 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
11f50 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
11f60 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
11f70 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
11f80 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
11f90 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
11fa0 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
11fb0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
11fc0 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
11fd0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
11fe0 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a  ite3_status()].*
11ff0 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  *   </ul>)^.** ^
12000 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
12010 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
12020 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
12030 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74  ult unless SQLit
12040 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
12050 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
12060 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
12070 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  =0 in which case
12080 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
12090 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
120a0 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
120b0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64   default..** </d
120c0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
120d0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
120e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
120f0 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74  NFIG_SCRATCH</dt
12100 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
12110 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
12120 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
12130 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
12140 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
12150 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
12160 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74 68  y.  There are th
12170 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20  ree arguments:  
12180 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62  A pointer an 8-b
12190 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d  yte.** aligned m
121a0 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f  emory buffer fro
121b0 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72 61  m which the scra
121c0 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
121d0 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e  will be.** drawn
121e0 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
121f0 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  ch scratch alloc
12200 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61  ation (sz),.** a
12210 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e  nd the maximum n
12220 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63 68  umber of scratch
12230 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29   allocations (N)
12240 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67  .  The sz.** arg
12250 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
12260 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a  multiple of 16..
12270 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
12280 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20  ument must be a 
12290 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d  pointer to an 8-
122a0 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66  byte aligned buf
122b0 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  fer.** of at lea
122c0 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66  st sz*N bytes of
122d0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c   memory..** ^SQL
122e0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20  ite will use no 
122f0 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63  more than two sc
12300 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70 65  ratch buffers pe
12310 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a  r thread.  So.**
12320 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74   N should be set
12330 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65 78   to twice the ex
12340 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e  pected maximum n
12350 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64 73  umber of threads
12360 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  ..** ^SQLite wil
12370 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65 20  l never require 
12380 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  a scratch buffer
12390 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68   that is more th
123a0 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68  an 6.** times th
123b0 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
123c0 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65  size. ^If SQLite
123d0 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64 64   needs needs add
123e0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74  itional.** scrat
123f0 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64  ch memory beyond
12400 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
12410 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67  d by this config
12420 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20  uration option, 
12430 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  then .** [sqlite
12440 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c  3_malloc()] will
12450 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
12460 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65  in the memory ne
12470 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  eded.</dd>.**.**
12480 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
12490 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74  _PAGECACHE]] <dt
124a0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
124b0 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a  AGECACHE</dt>.**
124c0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
124d0 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
124e0 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
124f0 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
12500 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74  can use for.** t
12510 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
12520 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65 20   cache with the 
12530 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61 63  default page cac
12540 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
12550 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e  n.  .** This con
12560 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c  figuration shoul
12570 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66  d not be used if
12580 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
12590 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63  define page.** c
125a0 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
125b0 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73  ion is loaded us
125c0 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ing the SQLITE_C
125d0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70  ONFIG_PCACHE2 op
125e0 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61  tion..** There a
125f0 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
12600 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
12610 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  n: A pointer to 
12620 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a  8-byte aligned.*
12630 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69  * memory, the si
12640 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65 20  ze of each page 
12650 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64  buffer (sz), and
12660 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70   the number of p
12670 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65  ages (N)..** The
12680 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f   sz argument sho
12690 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65 20  uld be the size 
126a0 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 64  of the largest d
126b0 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20  atabase page.** 
126c0 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20  (a power of two 
126d0 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20  between 512 and 
126e0 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69  32768) plus a li
126f0 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65  ttle extra for e
12700 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64  ach.** page head
12710 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68  er.  ^The page h
12720 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32 30  eader size is 20
12730 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65 70   to 40 bytes dep
12740 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65  ending on.** the
12750 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74 75   host architectu
12760 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d  re.  ^It is harm
12770 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d  less, apart from
12780 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f   the wasted memo
12790 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73  ry,.** to make s
127a0 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c  z a little too l
127b0 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73 74  arge.  The first
127c0 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  .** argument sho
127d0 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  uld point to an 
127e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74  allocation of at
127f0 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
12800 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
12810 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
12820 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76   the memory prov
12830 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72 73  ided by the firs
12840 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61  t argument to sa
12850 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d  tisfy its.** mem
12860 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68  ory needs for th
12870 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73 20  e first N pages 
12880 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f 20  that it adds to 
12890 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69  cache.  ^If addi
128a0 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63  tional.** page c
128b0 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e  ache memory is n
128c0 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61  eeded beyond wha
128d0 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79  t is provided by
128e0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68   this option, th
128f0 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65  en.** SQLite goe
12900 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61  s to [sqlite3_ma
12910 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20  lloc()] for the 
12920 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61  additional stora
12930 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65  ge space..** The
12940 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20   pointer in the 
12950 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d  first argument m
12960 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65  ust.** be aligne
12970 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
12980 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65  oundary or subse
12990 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f  quent behavior o
129a0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c  f SQLite.** will
129b0 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f   be undefined.</
129c0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
129d0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d  TE_CONFIG_HEAP]]
129e0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
129f0 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20  IG_HEAP</dt>.** 
12a00 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
12a10 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
12a20 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
12a30 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  er that SQLite w
12a40 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61  ill use.** for a
12a50 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69  ll of its dynami
12a60 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
12a70 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64  ion needs beyond
12a80 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a   those provided.
12a90 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54  ** for by [SQLIT
12aa0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
12ab0 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f  ] and [SQLITE_CO
12ac0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e  NFIG_PAGECACHE].
12ad0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
12ae0 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41  ree arguments: A
12af0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
12b00 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
12b10 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e  memory,.** the n
12b20 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
12b30 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66  n the memory buf
12b40 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e  fer, and the min
12b50 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
12b60 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  size..** ^If the
12b70 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
12b80 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
12b90 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  er) is NULL, the
12ba0 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74 73  n SQLite reverts
12bb0 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73  .** to using its
12bc0 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20   default memory 
12bd0 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73  allocator (the s
12be0 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69  ystem malloc() i
12bf0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a  mplementation),.
12c00 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70  ** undoing any p
12c10 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20  rior invocation 
12c20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  of [SQLITE_CONFI
12c30 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20  G_MALLOC].  ^If 
12c40 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f  the.** memory po
12c50 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
12c60 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51  L and either [SQ
12c70 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53  LITE_ENABLE_MEMS
12c80 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  YS3] or.** [SQLI
12c90 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
12ca0 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20  5] are defined, 
12cb0 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61  then the alterna
12cc0 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  tive memory.** a
12cd0 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61  llocator is enga
12ce0 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c  ged to handle al
12cf0 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d  l of SQLites mem
12d00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
12d10 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72  eeds..** The fir
12d20 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20  st pointer (the 
12d30 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20  memory pointer) 
12d40 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
12d50 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20  to an 8-byte.** 
12d60 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
12d70 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
12d80 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  of SQLite will b
12d90 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
12da0 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  The minimum allo
12db0 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63  cation size is c
12dc0 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20  apped at 2**12. 
12dd0 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65  Reasonable value
12de0 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e  s.** for the min
12df0 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
12e00 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68  size are 2**5 th
12e10 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e  rough 2**8.</dd>
12e20 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12e30 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c  CONFIG_MUTEX]] <
12e40 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12e50 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
12e60 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
12e70 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
12e80 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
12e90 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
12ea0 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
12eb0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
12ec0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
12ed0 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
12ee0 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
12ef0 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
12f00 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
12f10 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
12f20 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
12f30 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
12f40 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
12f50 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
12f60 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
12f70 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20   the.** content 
12f80 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
12f90 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
12fa0 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
12fb0 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
12fc0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12fd0 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
12fe0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
12ff0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
13000 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
13010 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
13020 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
13030 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
13040 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
13050 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
13060 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
13070 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
13080 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
13090 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
130a0 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
130b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
130c0 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
130d0 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
130e0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
130f0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
13100 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
13110 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  _GETMUTEX]] <dt>
13120 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
13130 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
13140 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
13150 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13160 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
13170 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
13180 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
13190 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
131a0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
131b0 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
131c0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
131d0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
131e0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
131f0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
13200 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
13210 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
13220 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
13230 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
13240 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
13250 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
13260 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
13270 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
13280 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
13290 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
132a0 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
132b0 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
132c0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
132d0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
132e0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
132f0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13300 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
13310 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
13320 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
13330 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
13340 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
13350 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
13360 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
13370 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
13380 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
13390 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
133a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
133b0 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
133c0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
133d0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
133e0 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
133f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
13400 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13410 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13420 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
13430 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
13440 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
13450 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
13460 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
13470 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
13480 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
13490 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
134a0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
134b0 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
134c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
134d0 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
134e0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
134f0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
13500 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
13510 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
13520 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
13530 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
13540 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
13550 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13560 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
13570 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
13580 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
13590 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
135a0 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
135b0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
135c0 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
135d0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
135e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
135f0 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
13600 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
13610 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
13620 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
13630 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
13640 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
13650 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
13660 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
13670 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
13680 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
13690 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
136a0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
136b0 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61   pointer to.** a
136c0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  n [sqlite3_pcach
136d0 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
136e0 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74  ct.  This object
136f0 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20 69   specifies the i
13700 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61  nterface.** to a
13710 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63   custom page cac
13720 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
13730 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61  n.)^  ^SQLite ma
13740 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  kes a copy of th
13750 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20  e.** object and 
13760 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67 65  uses it for page
13770 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c   cache memory al
13780 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a  locations.</dd>.
13790 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
137a0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
137b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
137c0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c  NFIG_GETPCACHE2<
137d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
137e0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
137f0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
13800 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f  nt which is a po
13810 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b  inter to an.** [
13820 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
13830 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e  ethods2] object.
13840 20 20 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20    SQLite copies 
13850 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
13860 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  * page cache imp
13870 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f  lementation into
13880 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20   that object.)^ 
13890 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
138a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d  LITE_CONFIG_LOG]
138b0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
138c0 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20  FIG_LOG</dt>.** 
138d0 3c 64 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f  <dd> The SQLITE_
138e0 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
138f0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e  n is used to con
13900 66 69 67 75 72 65 20 74 68 65 20 53 51 4c 69 74  figure the SQLit
13910 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72  e.** global [err
13920 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68  or log]..** (^Th
13930 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
13940 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
13950 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
13960 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
13970 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
13980 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
13990 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
139a0 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
139b0 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
139c0 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
139d0 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
139e0 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
139f0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
13a00 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
13a10 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
13a20 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
13a30 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
13a40 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
13a50 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
13a60 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
13a70 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
13a80 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
13a90 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
13aa0 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
13ab0 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
13ac0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
13ad0 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
13ae0 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
13af0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
13b00 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
13b10 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
13b20 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
13b30 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
13b40 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
13b50 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
13b60 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
13b70 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
13b80 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
13b90 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
13ba0 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
13bb0 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
13bc0 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
13bd0 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
13be0 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
13bf0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
13c00 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
13c10 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
13c20 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
13c30 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
13c40 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
13c50 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
13c60 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
13c70 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
13c80 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
13c90 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
13ca0 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
13cb0 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
13cc0 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
13cd0 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
13ce0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
13cf0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
13d00 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
13d10 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
13d20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
13d30 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
13d40 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
13d50 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
13d60 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
13d70 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
13d80 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
13d90 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
13da0 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69  URI.** <dd>^(Thi
13db0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13dc0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13dd0 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66   of type int. If
13de0 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a   non-zero, then.
13df0 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  ** URI handling 
13e00 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
13e10 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61  led. If the para
13e20 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74  meter is zero, t
13e30 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  hen URI handling
13e40 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  .** is globally 
13e50 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20  disabled.)^ ^If 
13e60 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
13e70 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
13e80 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a  , all filenames.
13e90 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  ** passed to [sq
13ea0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b  lite3_open()], [
13eb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
13ec0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
13ed0 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65  n16()] or.** spe
13ee0 63 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f  cified as part o
13ef0 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61  f [ATTACH] comma
13f00 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65  nds are interpre
13f10 74 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67  ted as URIs, reg
13f20 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68  ardless.** of wh
13f30 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
13f40 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
13f50 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  I] flag is set w
13f60 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
13f70 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  .** connection i
13f80 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74  s opened. ^If it
13f90 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
13fa0 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73  abled, filenames
13fb0 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74   are.** only int
13fc0 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
13fd0 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f   if the SQLITE_O
13fe0 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20  PEN_URI flag is 
13ff0 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  set when the.** 
14000 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
14010 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e  ion is opened. ^
14020 28 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49  (By default, URI
14030 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f   handling is glo
14040 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65  bally.** disable
14050 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76  d. The default v
14060 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e  alue may be chan
14070 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67  ged by compiling
14080 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
14090 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79  LITE_USE_URI] sy
140a0 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a  mbol defined.)^.
140b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
140c0 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49  ONFIG_COVERING_I
140d0 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e  NDEX_SCAN]] <dt>
140e0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f  SQLITE_CONFIG_CO
140f0 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41  VERING_INDEX_SCA
14100 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f  N.** <dd>^This o
14110 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
14120 6e 67 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67  ngle integer arg
14130 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 69  ument which is i
14140 6e 74 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a  nterpreted as.**
14150 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72   a boolean in or
14160 64 65 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  der to enable or
14170 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
14180 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
14190 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c  ices for.** full
141a0 20 74 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20   table scans in 
141b0 74 68 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69  the query optimi
141c0 7a 65 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75  zer.  ^The defau
141d0 6c 74 20 73 65 74 74 69 6e 67 20 69 73 20 64 65  lt setting is de
141e0 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74  termined.** by t
141f0 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57  he [SQLITE_ALLOW
14200 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
14210 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SCAN] compile-ti
14220 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73  me option, or is
14230 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74   "on".** if that
14240 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
14250 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e  tion is omitted.
14260 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20  .** The ability 
14270 74 6f 20 64 69 73 61 62 6c 65 20 74 68 65 20 75  to disable the u
14280 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69  se of covering i
14290 6e 64 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20  ndices for full 
142a0 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69  table scans.** i
142b0 73 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69  s because some i
142c0 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64  ncorrectly coded
142d0 20 6c 65 67 61 63 79 20 61 70 70 6c 69 63 61 74   legacy applicat
142e0 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75  ions might malfu
142f0 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74  nction.** when t
14300 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
14310 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f  is enabled.  Pro
14320 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69  viding the abili
14330 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65  ty to.** disable
14340 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
14350 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64  n allows the old
14360 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63  er, buggy applic
14370 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f  ation code to wo
14380 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68  rk.** without ch
14390 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e  ange even with n
143a0 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
143b0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b   SQLite..**.** [
143c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
143d0 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45  CACHE]] [[SQLITE
143e0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
143f0 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
14400 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
14410 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  and SQLITE_CONFI
14420 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c  G_GETPCACHE.** <
14430 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  dd> These option
14440 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61  s are obsolete a
14450 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
14460 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64   used by new cod
14470 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72  e..** They are r
14480 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
14490 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
144a0 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20  ity but are now 
144b0 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e  no-ops..** </dd>
144c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
144d0 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a  CONFIG_SQLLOG]].
144e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
144f0 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c  NFIG_SQLLOG.** <
14500 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  dd>This option i
14510 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
14520 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f   if sqlite is co
14530 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
14540 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
14550 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72  E_SQLLOG] pre-pr
14560 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65  ocessor macro de
14570 66 69 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74  fined. The first
14580 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
14590 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72  .** be a pointer
145a0 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
145b0 66 20 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76  f type void(*)(v
145c0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f  oid*,sqlite3*,co
145d0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e  nst char*, int).
145e0 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73  .** The second s
145f0 68 6f 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65  hould be of type
14600 20 28 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61   (void*). The ca
14610 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
14620 64 20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79  d by the library
14630 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70  .** in three sep
14640 61 72 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e  arate circumstan
14650 63 65 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20  ces, identified 
14660 62 79 20 74 68 65 20 76 61 6c 75 65 20 70 61 73  by the value pas
14670 73 65 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f  sed as the.** fo
14680 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20  urth parameter. 
14690 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  If the fourth pa
146a0 72 61 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68  rameter is 0, th
146b0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
146c0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61  connection.** pa
146d0 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  ssed as the seco
146e0 6e 64 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  nd argument has 
146f0 6a 75 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64  just been opened
14700 2e 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75  . The third argu
14710 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74  ment.** points t
14720 6f 20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61  o a buffer conta
14730 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f  ining the name o
14740 66 20 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62  f the main datab
14750 61 73 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65  ase file. If the
14760 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d  .** fourth param
14770 65 74 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20  eter is 1, then 
14780 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
14790 74 20 74 68 61 74 20 74 68 65 20 74 68 69 72 64  t that the third
147a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f   parameter.** po
147b0 69 6e 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74  ints to has just
147c0 20 62 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20   been executed. 
147d0 4f 72 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74  Or, if the fourt
147e0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 32  h parameter is 2
147f0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f  , then.** the co
14800 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70  nnection being p
14810 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
14820 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
14830 20 62 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54   being closed. T
14840 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
14850 6d 65 74 65 72 20 69 73 20 70 61 73 73 65 64 20  meter is passed 
14860 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73  NULL In this cas
14870 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f  e.  An example o
14880 66 20 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20  f using this.** 
14890 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
148a0 74 69 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e  tion can be seen
148b0 20 69 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71   in the "test_sq
148c0 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66  llog.c" source f
148d0 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61  ile in.** the ca
148e0 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73  nonical SQLite s
148f0 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e  ource tree.</dd>
14900 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14910 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45  CONFIG_MMAP_SIZE
14920 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
14930 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
14940 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45  E.** <dd>^SQLITE
14950 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
14960 45 20 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62  E takes two 64-b
14970 69 74 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69  it integer (sqli
14980 74 65 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65  te3_int64) value
14990 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68  s.** that are th
149a0 65 20 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73  e default mmap s
149b0 69 7a 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64  ize limit (the d
149c0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66  efault setting f
149d0 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d  or.** [PRAGMA mm
149e0 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68  ap_size]) and th
149f0 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65  e maximum allowe
14a00 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69  d mmap size limi
14a10 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  t..** ^The defau
14a20 6c 74 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62  lt setting can b
14a30 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
14a40 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
14a50 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a  nnection using.*
14a60 2a 20 65 69 74 68 65 72 20 74 68 65 20 5b 50 52  * either the [PR
14a70 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20  AGMA mmap_size] 
14a80 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75  command, or by u
14a90 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  sing the.** [SQL
14aa0 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
14ab0 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
14ac0 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75  l.  ^(The maximu
14ad0 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
14ae0 69 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65  ize.** cannot be
14af0 20 63 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d   changed at run-
14b00 74 69 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74  time.  Nor may t
14b10 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77  he maximum allow
14b20 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20  ed mmap size.** 
14b30 65 78 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69  exceed the compi
14b40 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20  le-time maximum 
14b50 6d 6d 61 70 20 73 69 7a 65 20 73 65 74 20 62 79  mmap size set by
14b60 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
14b70 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63  MAX_MMAP_SIZE] c
14b80 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14b90 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74  on.)^.** ^If eit
14ba0 68 65 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  her argument to 
14bb0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e  this option is n
14bc0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
14bd0 61 74 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a  at argument is.*
14be0 2a 20 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73  * changed to its
14bf0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65   compile-time de
14c00 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fault..**.** [[S
14c10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
14c20 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a  32_HEAPSIZE]].**
14c30 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14c40 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a  IG_WIN32_HEAPSIZ
14c50 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f  E.** <dd>^This o
14c60 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
14c70 61 69 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74  ailable if SQLit
14c80 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f  e is compiled fo
14c90 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74  r Windows.** wit
14ca0 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49  h the [SQLITE_WI
14cb0 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d  N32_MALLOC] pre-
14cc0 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
14cd0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49  defined..** SQLI
14ce0 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
14cf0 48 45 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61  HEAPSIZE takes a
14d00 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
14d10 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a   integer value.*
14d20 2a 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  * that specifies
14d30 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a   the maximum siz
14d40 65 20 6f 66 20 74 68 65 20 63 72 65 61 74 65 64  e of the created
14d50 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a   heap..** </dl>.
14d60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
14d70 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
14d80 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
14d90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
14da0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
14db0 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
14dc0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
14dd0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
14de0 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
14df0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
14e00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
14e10 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
14e20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14e30 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
14e40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
14e50 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
14e60 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
14e70 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
14e80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14e90 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
14ea0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
14eb0 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
14ec0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
14ed0 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
14ee0 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
14ef0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
14f00 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14f10 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
14f20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
14f30 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
14f40 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
14f50 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
14f60 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
14f70 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
14f80 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
14f90 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
14fa0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
14fb0 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
14fc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
14fd0 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
14fe0 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
14ff0 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
15000 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
15010 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
15020 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
15030 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
15040 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
15050 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
15060 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
15070 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
15080 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15090 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
150a0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
150b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
150c0 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
150d0 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
150e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
150f0 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
15100 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
15110 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
15120 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15130 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
15140 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
15150 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15160 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
15170 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
15180 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
15190 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
151a0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
151b0 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
151c0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
151d0 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
151e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
151f0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
15200 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23   20  /* int */.#
15210 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15220 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20  NFIG_SQLLOG     
15230 20 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67    21  /* xSqllog
15240 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69  , void* */.#defi
15250 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15260 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32  _MMAP_SIZE    22
15270 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74    /* sqlite3_int
15280 36 34 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  64, sqlite3_int6
15290 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  4 */.#define SQL
152a0 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
152b0 5f 48 45 41 50 53 49 5a 45 20 20 20 20 20 20 32  _HEAPSIZE      2
152c0 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20  3  /* int nByte 
152d0 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
152e0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
152f0 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72  nection Configur
15300 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
15310 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
15320 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
15330 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
15340 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15350 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
15360 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
15370 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
15380 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
15390 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
153a0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
153b0 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
153c0 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
153d0 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
153e0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
153f0 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
15400 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15410 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
15420 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
15430 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
15440 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
15450 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
15460 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
15470 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
15480 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
15490 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68  all worked.  ^Th
154a0 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  e [sqlite3_db_co
154b0 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
154c0 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a  e will return a.
154d0 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72  ** non-zero [err
154e0 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69  or code] if a di
154f0 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e  scontinued or un
15500 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67  supported config
15510 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a  uration option.*
15520 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a  * is invoked..**
15530 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e  .** <dl>.** <dt>
15540 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
15550 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
15560 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
15570 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20  ion takes three 
15580 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d  additional argum
15590 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
155a0 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f  ine the .** [loo
155b0 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
155c0 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75  locator] configu
155d0 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b  ration for the [
155e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
155f0 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69  ion]..** ^The fi
15600 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68  rst argument (th
15610 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
15620 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62  r to [sqlite3_db
15630 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a  _config()] is a.
15640 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20  ** pointer to a 
15650 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f  memory buffer to
15660 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69   use for lookasi
15670 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54  de memory..** ^T
15680 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15690 74 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49  t after the SQLI
156a0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
156b0 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61  ASIDE verb.** ma
156c0 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69  y be NULL in whi
156d0 63 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77  ch case SQLite w
156e0 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  ill allocate the
156f0 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  .** lookaside bu
15700 66 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e  ffer itself usin
15710 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  g [sqlite3_mallo
15720 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e  c()]. ^The secon
15730 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
15740 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
15750 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
15760 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74  er slot.  ^The t
15770 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
15780 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
15790 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69  * slots.  The si
157a0 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
157b0 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
157c0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67  gument must be g
157d0 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f  reater than.** o
157e0 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70  r equal to the p
157f0 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65  roduct of the se
15800 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61  cond and third a
15810 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62  rguments.  The b
15820 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65  uffer.** must be
15830 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
15840 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20  -byte boundary. 
15850 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
15860 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53  argument to.** S
15870 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15880 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20  OOKASIDE is not 
15890 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c  a multiple of 8,
158a0 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c   it is internall
158b0 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77  y.** rounded dow
158c0 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d  n to the next sm
158d0 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  aller multiple o
158e0 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b  f 8.  ^(The look
158f0 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  aside memory.** 
15900 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
15910 72 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  r a database con
15920 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79  nection can only
15930 20 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e   be changed when
15940 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74   that.** connect
15950 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65  ion is not curre
15960 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61  ntly using looka
15970 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20  side memory, or 
15980 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a  in other words.*
15990 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72  * when the "curr
159a0 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72  ent value" retur
159b0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
159c0 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c  e3_db_status](D,
159d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
159e0 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69  OOKASIDE],...) i
159f0 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61  s zero..** Any a
15a00 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65  ttempt to change
15a10 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
15a20 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74  emory configurat
15a30 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69  ion when lookasi
15a40 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20  de.** memory is 
15a50 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68  in use leaves th
15a60 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
15a70 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65  unchanged and re
15a80 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  turns .** [SQLIT
15a90 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a  E_BUSY].)^</dd>.
15aa0 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  **.** <dt>SQLITE
15ab0 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
15ac0 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _FKEY</dt>.** <d
15ad0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
15ae0 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c  is used to enabl
15af0 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
15b00 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a   enforcement of.
15b10 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20  ** [foreign key 
15b20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54  constraints].  T
15b30 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
15b40 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
15b50 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
15b60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
15b70 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
15b80 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
15b90 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  le FK enforcemen
15ba0 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74  t,.** positive t
15bb0 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f  o enable FK enfo
15bc0 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74  rcement or negat
15bd0 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20  ive to leave FK 
15be0 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75  enforcement.** u
15bf0 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73  nchanged.  The s
15c00 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
15c10 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15c20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
15c30 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
15c40 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
15c50 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46  dicate whether F
15c60 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73  K enforcement is
15c70 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f   off or on.** fo
15c80 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
15c90 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
15ca0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
15cb0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
15cc0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
15cd0 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d   the FK enforcem
15ce0 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ent setting is n
15cf0 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
15d00 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
15d10 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
15d20 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52  G_ENABLE_TRIGGER
15d30 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15d40 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  his option is us
15d50 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20  ed to enable or 
15d60 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20  disable [CREATE 
15d70 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65  TRIGGER | trigge
15d80 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68  rs]..** There sh
15d90 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
15da0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
15db0 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
15dc0 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
15dd0 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
15de0 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67   to disable trig
15df0 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  gers,.** positiv
15e00 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67  e to enable trig
15e10 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65  gers or negative
15e20 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65   to leave the se
15e30 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e  tting unchanged.
15e40 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70  .** The second p
15e50 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
15e60 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
15e70 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
15e80 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
15e90 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
15ea0 77 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73  whether triggers
15eb0 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72   are disabled or
15ec0 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c   enabled.** foll
15ed0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
15ee0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
15ef0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
15f00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
15f10 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
15f20 68 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69  he trigger setti
15f30 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
15f40 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
15f50 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  *.** </dl>.*/.#d
15f60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
15f70 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
15f80 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76        1001  /* v
15f90 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a  oid* int int */.
15fa0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
15fb0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
15fc0 4b 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a  KEY     1002  /*
15fd0 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65   int int* */.#de
15fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
15ff0 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
16000 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e  GER  1003  /* in
16010 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a  t int* */.../*.*
16020 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62  * CAPI3REF: Enab
16030 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78  le Or Disable Ex
16040 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
16050 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  des.**.** ^The s
16060 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
16070 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72  result_codes() r
16080 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f  outine enables o
16090 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a  r disables the.*
160a0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
160b0 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72  lt codes] featur
160c0 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68  e of SQLite. ^Th
160d0 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  e extended resul
160e0 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64  t.** codes are d
160f0 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
16100 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  lt for historica
16110 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  l compatibility.
16120 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
16130 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e  nt sqlite3_exten
16140 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73  ded_result_codes
16150 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
16160 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  noff);../*.** CA
16170 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73  PI3REF: Last Ins
16180 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20  ert Rowid.**.** 
16190 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 6d  ^Each entry in m
161a0 6f 73 74 20 53 51 4c 69 74 65 20 74 61 62 6c 65  ost SQLite table
161b0 73 20 28 65 78 63 65 70 74 20 66 6f 72 20 5b 57  s (except for [W
161c0 49 54 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61  ITHOUT ROWID] ta
161d0 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20 61 20 75  bles).** has a u
161e0 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67  nique 64-bit sig
161f0 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b  ned.** integer k
16200 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52  ey called the [R
16210 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e  OWID | "rowid"].
16220 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61   ^The rowid is a
16230 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a  lways available.
16240 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61  ** as an undecla
16250 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64  red column named
16260 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20   ROWID, OID, or 
16270 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20  _ROWID_ as long 
16280 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65  as those.** name
16290 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75  s are not also u
162a0 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c  sed by explicitl
162b0 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  y declared colum
162c0 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74  ns. ^If.** the t
162d0 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d  able has a colum
162e0 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47  n of type [INTEG
162f0 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20  ER PRIMARY KEY] 
16300 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  then that column
16310 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61  .** is another a
16320 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77  lias for the row
16330 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  id..**.** ^The s
16340 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
16350 72 74 5f 72 6f 77 69 64 28 44 29 20 69 6e 74 65  rt_rowid(D) inte
16360 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
16370 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65  e [rowid] of the
16380 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74   .** most recent
16390 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
163a0 45 52 54 5d 20 69 6e 74 6f 20 61 20 72 6f 77 69  ERT] into a rowi
163b0 64 20 74 61 62 6c 65 20 6f 72 20 5b 76 69 72 74  d table or [virt
163c0 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e  ual table].** on
163d0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
163e0 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65  tion D..** ^Inse
163f0 72 74 73 20 69 6e 74 6f 20 5b 57 49 54 48 4f 55  rts into [WITHOU
16400 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73 20  T ROWID] tables 
16410 61 72 65 20 6e 6f 74 20 72 65 63 6f 72 64 65 64  are not recorded
16420 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63  ..** ^If no succ
16430 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73  essful [INSERT]s
16440 20 69 6e 74 6f 20 72 6f 77 69 64 20 74 61 62 6c   into rowid tabl
16450 65 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  es.** have ever 
16460 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 65 20  occurred on the 
16470 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16480 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68 65 6e 20  ion D, .** then 
16490 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
164a0 65 72 74 5f 72 6f 77 69 64 28 44 29 20 72 65 74  ert_rowid(D) ret
164b0 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
164c0 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54   ^(If an [INSERT
164d0 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  ] occurs within 
164e0 61 20 74 72 69 67 67 65 72 20 6f 72 20 77 69 74  a trigger or wit
164f0 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74  hin a [virtual t
16500 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c  able].** method,
16510 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69   then this routi
16520 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74  ne will return t
16530 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
16540 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
16550 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  w as long as the
16560 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
16570 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
16580 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
16590 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69  But once the tri
165a0 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
165b0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64  table method end
165c0 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  s, the value ret
165d0 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69  urned .** by thi
165e0 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74  s routine revert
165f0 73 20 74 6f 20 77 68 61 74 20 69 74 20 77 61 73  s to what it was
16600 20 62 65 66 6f 72 65 20 74 68 65 20 74 72 69 67   before the trig
16610 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a  ger or virtual.*
16620 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62  * table method b
16630 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41  egan.)^.**.** ^A
16640 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20  n [INSERT] that 
16650 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63  fails due to a c
16660 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
16670 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20  ion is not a.** 
16680 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
16690 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74  RT] and does not
166a0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
166b0 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68  e returned by th
166c0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20  is.** routine.  
166d0 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20  ^Thus INSERT OR 
166e0 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20  FAIL, INSERT OR 
166f0 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f  IGNORE, INSERT O
16700 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61  R ROLLBACK,.** a
16710 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f  nd INSERT OR ABO
16720 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67  RT make no chang
16730 65 73 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e  es to the return
16740 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a   value of this.*
16750 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74  * routine when t
16760 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66  heir insertion f
16770 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e  ails.  ^(When IN
16780 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a  SERT OR REPLACE.
16790 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20  ** encounters a 
167a0 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61  constraint viola
167b0 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f  tion, it does no
167c0 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20  t fail.  The.** 
167d0 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73  INSERT continues
167e0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61   to completion a
167f0 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f  fter deleting ro
16800 77 73 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a  ws that caused.*
16810 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  * the constraint
16820 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45   problem so INSE
16830 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69  RT OR REPLACE wi
16840 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65  ll always change
16850 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76  .** the return v
16860 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74  alue of this int
16870 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  erface.)^.**.** 
16880 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
16890 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  s of this routin
168a0 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69  e, an [INSERT] i
168b0 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a  s considered to.
168c0 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66 75 6c  ** be successful
168d0 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 73   even if it is s
168e0 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c  ubsequently roll
168f0 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54  ed back..**.** T
16900 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  his function is 
16910 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51  accessible to SQ
16920 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61  L statements via
16930 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e   the.** [last_in
16940 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c  sert_rowid() SQL
16950 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
16960 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
16970 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20  thread performs 
16980 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f  a new [INSERT] o
16990 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61  n the same.** da
169a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
169b0 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c  n while the [sql
169c0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
169d0 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e  _rowid()].** fun
169e0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
169f0 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65   and thus change
16a00 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72  s the last inser
16a10 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68  t [rowid],.** th
16a20 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
16a30 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
16a40 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
16a50 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70  wid()] is.** unp
16a60 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d  redictable and m
16a70 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65  ight not equal e
16a80 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72  ither the old or
16a90 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74   the new.** last
16aa0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e   insert [rowid].
16ab0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
16ac0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
16ad0 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
16ae0 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29  _rowid(sqlite3*)
16af0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
16b00 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d  F: Count The Num
16b10 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
16b20 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
16b30 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
16b40 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
16b50 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74 68  database rows th
16b60 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a  at were changed.
16b70 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f  ** or inserted o
16b80 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68 65  r deleted by the
16b90 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
16ba0 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61  ompleted SQL sta
16bb0 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65  tement.** on the
16bc0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
16bd0 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
16be0 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61   by the first pa
16bf0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e  rameter..** ^(On
16c00 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74 20  ly changes that 
16c10 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70 65  are directly spe
16c20 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b 49  cified by the [I
16c30 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d  NSERT], [UPDATE]
16c40 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d  ,.** or [DELETE]
16c50 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63   statement are c
16c60 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61  ounted.  Auxilia
16c70 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ry changes cause
16c80 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73  d by.** triggers
16c90 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79   or [foreign key
16ca0 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f   actions] are no
16cb0 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65  t counted.)^ Use
16cc0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
16cd0 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
16ce0 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69  ] function to fi
16cf0 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d  nd the total num
16d00 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a  ber of changes.*
16d10 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e  * including chan
16d20 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74 72  ges caused by tr
16d30 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69  iggers and forei
16d40 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a  gn key actions..
16d50 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74  **.** ^Changes t
16d60 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61 72  o a view that ar
16d70 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61  e simulated by a
16d80 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
16d90 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f  igger].** are no
16da0 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79  t counted.  Only
16db0 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e   real table chan
16dc0 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  ges are counted.
16dd0 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20  .**.** ^(A "row 
16de0 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68 61  change" is a cha
16df0 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20  nge to a single 
16e00 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  row of a single 
16e10 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20  table.** caused 
16e20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45  by an INSERT, DE
16e30 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20  LETE, or UPDATE 
16e40 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73  statement.  Rows
16e50 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61   that.** are cha
16e60 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66 66  nged as side eff
16e70 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45  ects of [REPLACE
16e80 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73  ] constraint res
16e90 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c  olution,.** roll
16ea0 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63  back, ABORT proc
16eb0 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41  essing, [DROP TA
16ec0 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20  BLE], or by any 
16ed0 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69  other.** mechani
16ee0 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74  sms do not count
16ef0 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20 63   as direct row c
16f00 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  hanges.)^.**.** 
16f10 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65  A "trigger conte
16f20 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f  xt" is a scope o
16f30 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74  f execution that
16f40 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65   begins and.** e
16f50 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63 72  nds with the scr
16f60 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45  ipt of a [CREATE
16f70 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
16f80 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51  er]. .** Most SQ
16f90 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
16fa0 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75  .** evaluated ou
16fb0 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69  tside of any tri
16fc0 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20 74  gger.  This is t
16fd0 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a  he "top level".*
16fe0 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
16ff0 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65 72  t.  If a trigger
17000 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20   fires from the 
17010 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20  top level, a.** 
17020 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74  new trigger cont
17030 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20 66  ext is entered f
17040 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20  or the duration 
17050 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74  of that one.** t
17060 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69 67  rigger.  Subtrig
17070 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62 63  gers create subc
17080 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65 69  ontexts for thei
17090 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  r duration..**.*
170a0 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  * ^Calling [sqli
170b0 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b  te3_exec()] or [
170c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
170d0 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73  recursively does
170e0 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61  .** not create a
170f0 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
17100 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  text..**.** ^Thi
17110 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
17120 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
17130 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
17140 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f  ges in the.** mo
17150 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54  st recent INSERT
17160 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
17170 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69  ETE statement wi
17180 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  thin the same.**
17190 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
171a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77  ..**.** ^Thus, w
171b0 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  hen called from 
171c0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74  the top level, t
171d0 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
171e0 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  urns the.** numb
171f0 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e  er of changes in
17200 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
17210 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
17220 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
17230 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64  at also occurred
17240 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65   at the top leve
17250 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65  l.  ^(Within the
17260 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67   body of a trigg
17270 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74  er,.** the sqlit
17280 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74  e3_changes() int
17290 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63 61  erface can be ca
172a0 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  lled to find the
172b0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
172c0 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
172d0 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c  t recently compl
172e0 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44  eted INSERT, UPD
172f0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
17300 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  * statement with
17310 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74  in the body of t
17320 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e  he same trigger.
17330 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
17340 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64   number returned
17350 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
17360 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75  e changes.** cau
17370 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67 65  sed by subtrigge
17380 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68  rs since those h
17390 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f  ave their own co
173a0 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  ntext.)^.**.** S
173b0 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
173c0 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
173d0 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
173e0 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
173f0 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
17400 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73  and the [changes
17410 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
17420 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
17430 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
17440 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
17450 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
17460 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
17470 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  ile [sqlite3_cha
17480 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
17490 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
174a0 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73  e returned.** is
174b0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
174c0 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
174d0 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
174e0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61   int sqlite3_cha
174f0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
17500 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
17510 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
17520 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
17530 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
17540 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
17550 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
17560 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
17570 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50  [INSERT],.** [UP
17580 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
17590 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  ] statements sin
175a0 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
175b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
175c0 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68   opened..** ^(Th
175d0 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64  e count returned
175e0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
175f0 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c  l_changes() incl
17600 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73  udes all changes
17610 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52  .** from all [CR
17620 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
17630 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73  rigger] contexts
17640 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64   and changes mad
17650 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  e by.** [foreign
17660 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48   key actions]. H
17670 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63  owever,.** the c
17680 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
17690 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
176a0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
176b0 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
176c0 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
176d0 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
176e0 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b  processing, or [
176f0 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63  DROP TABLE] proc
17700 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20  essing.  The.** 
17710 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
17720 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76  nclude rows of v
17730 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61  iews that fire a
17740 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
17750 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67  igger],.** thoug
17760 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44  h if the INSTEAD
17770 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65   OF trigger make
17780 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73  s changes of its
17790 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e   own, those chan
177a0 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e  ges .** are coun
177b0 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73  ted.)^.** ^The s
177c0 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
177d0 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
177e0 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67  counts the chang
177f0 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a  es as soon as.**
17800 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
17810 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
17820 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65  s completed (whe
17830 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
17840 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73  handle.** is pas
17850 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
17860 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
17870 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
17880 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
17890 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
178a0 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
178b0 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
178c0 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
178d0 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
178e0 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
178f0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
17900 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
17910 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
17920 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
17930 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17940 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
17950 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
17960 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
17970 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
17980 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
17990 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
179a0 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
179b0 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
179c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74   int sqlite3_tot
179d0 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  al_changes(sqlit
179e0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
179f0 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74  I3REF: Interrupt
17a00 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20   A Long-Running 
17a10 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  Query.**.** ^Thi
17a20 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65  s function cause
17a30 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61  s any pending da
17a40 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
17a50 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a   to abort and.**
17a60 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20 65   return at its e
17a70 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e  arliest opportun
17a80 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e  ity. This routin
17a90 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a  e is typically.*
17aa0 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70  * called in resp
17ab0 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20 61  onse to a user a
17ac0 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72  ction such as pr
17ad0 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a  essing "Cancel".
17ae0 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65  ** or Ctrl-C whe
17af0 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e 74  re the user want
17b00 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f  s a long query o
17b10 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74  peration to halt
17b20 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e  .** immediately.
17b30 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61  .**.** ^It is sa
17b40 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
17b50 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74  routine from a t
17b60 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74 20  hread different 
17b70 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65  from the.** thre
17b80 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72 65  ad that is curre
17b90 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65  ntly running the
17ba0 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74   database operat
17bb0 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20  ion.  But it.** 
17bc0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63  is not safe to c
17bd0 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  all this routine
17be0 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
17bf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68  e connection] th
17c00 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20  at.** is closed 
17c10 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62  or might close b
17c20 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e  efore sqlite3_in
17c30 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72 6e  terrupt() return
17c40 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  s..**.** ^If an 
17c50 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
17c60 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e   very nearly fin
17c70 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69 6d  ished at the tim
17c80 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65  e when.** sqlite
17c90 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69 73  3_interrupt() is
17ca0 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74   called, then it
17cb0 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20   might not have 
17cc0 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a  an opportunity.*
17cd0 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70  * to be interrup
17ce0 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f  ted and might co
17cf0 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65  ntinue to comple
17d00 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  tion..**.** ^An 
17d10 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  SQL operation th
17d20 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74 65  at is interrupte
17d30 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  d will return [S
17d40 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
17d50 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74  ..** ^If the int
17d60 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65  errupted SQL ope
17d70 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53  ration is an INS
17d80 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
17d90 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69  DELETE.** that i
17da0 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c  s inside an expl
17db0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
17dc0 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72  , then the entir
17dd0 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a  e transaction.**
17de0 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20   will be rolled 
17df0 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c  back automatical
17e00 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ly..**.** ^The s
17e10 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
17e20 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65  (D) call is in e
17e30 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20  ffect until all 
17e40 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
17e50 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  g.** SQL stateme
17e60 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  nts on [database
17e70 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63   connection] D c
17e80 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e  omplete.  ^Any n
17e90 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
17ea0 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
17eb0 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
17ec0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
17ed0 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66  t() call and bef
17ee0 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e  ore the .** runn
17ef0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72  ing statements r
17f00 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20  eaches zero are 
17f10 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20 69  interrupted as i
17f20 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a  f they had been.
17f30 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72  ** running prior
17f40 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
17f50 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c  interrupt() call
17f60 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74  .  ^New SQL stat
17f70 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
17f80 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
17f90 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61   the running sta
17fa0 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61  tement count rea
17fb0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a  ches zero are.**
17fc0 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62 79   not effected by
17fd0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
17fe0 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20  errupt()..** ^A 
17ff0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
18000 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68 61  interrupt(D) tha
18010 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68  t occurs when th
18020 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69  ere are no runni
18030 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
18040 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20  ents is a no-op 
18050 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63  and has no effec
18060 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  t on SQL stateme
18070 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
18080 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
18090 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
180a0 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72  upt() call retur
180b0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ns..**.** If the
180c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
180d0 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c  tion closes whil
180e0 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  e [sqlite3_inter
180f0 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75  rupt()].** is ru
18100 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74  nning then bad t
18110 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c  hings will likel
18120 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c  y happen..*/.SQL
18130 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
18140 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
18150 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
18160 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
18170 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
18180 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
18190 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
181a0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
181b0 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d  eful during comm
181c0 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
181d0 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
181e0 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
181f0 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
18200 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d  ms to form a com
18210 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
18220 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
18230 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
18240 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
18250 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
18260 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
18270 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68  or parsing.  ^Th
18280 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
18290 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70  urn 1 if the inp
182a0 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
182b0 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
182c0 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
182d0 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65  ent.  ^A stateme
182e0 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
182f0 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
18300 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
18310 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
18320 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
18330 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
18340 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
18350 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
18360 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20  t.  ^Semicolons 
18370 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
18380 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
18390 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
183a0 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
183b0 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
183c0 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
183d0 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
183e0 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
183f0 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
18400 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
18410 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
18420 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
18430 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
18440 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57   terminator.  ^W
18450 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64  hitespace.** and
18460 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66   comments that f
18470 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20  ollow the final 
18480 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67  semicolon are ig
18490 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nored..**.** ^Th
184a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
184b0 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
184c0 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
184d0 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20  lete.  ^If a.** 
184e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
184f0 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51  n fails, then SQ
18500 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65  LITE_NOMEM is re
18510 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
18520 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
18530 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
18540 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
18550 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
18560 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
18570 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
18580 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  L..**.** ^(If SQ
18590 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65  Lite has not bee
185a0 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73  n initialized us
185b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ing [sqlite3_ini
185c0 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72  tialize()] prior
185d0 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67   .** to invoking
185e0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
185f0 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74  e16() then sqlit
18600 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
18610 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75  is invoked.** au
18620 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
18630 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18640 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e  6().  If that in
18650 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69  itialization fai
18660 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ls,.** then the 
18670 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
18680 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  m sqlite3_comple
18690 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e  te16() will be n
186a0 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72  on-zero.** regar
186b0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
186c0 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75   or not the inpu
186d0 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74  t SQL is complet
186e0 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  e.)^.**.** The i
186f0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
18700 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
18710 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
18720 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
18730 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
18740 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
18750 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
18760 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
18770 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
18780 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
18790 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
187a0 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  r..*/.SQLITE_API
187b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d   int sqlite3_com
187c0 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72  plete(const char
187d0 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   *sql);.SQLITE_A
187e0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
187f0 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
18800 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
18810 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
18820 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
18830 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
18840 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
18850 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
18860 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
18870 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
18880 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
18890 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
188a0 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
188b0 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
188c0 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e  se table that an
188d0 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
188e0 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c  or process has l
188f0 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ocked..**.** ^If
18900 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
18910 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
18920 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
18930 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
18940 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
18950 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
18960 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
18970 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
18980 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
18990 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
189a0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
189b0 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
189c0 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
189d0 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
189e0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
189f0 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
18a00 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
18a10 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
18a20 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
18a30 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
18a40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
18a50 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
18a60 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
18a70 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
18a80 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
18a90 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
18aa0 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
18ab0 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
18ac0 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
18ad0 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
18ae0 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
18af0 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
18b00 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
18b10 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
18b20 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
18b30 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
18b40 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
18b50 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
18b60 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
18b70 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
18b80 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
18b90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
18ba0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
18bb0 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
18bc0 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
18bd0 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
18be0 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
18bf0 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
18c00 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
18c10 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
18c20 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
18c30 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
18c40 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
18c50 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
18c60 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
18c70 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
18c80 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
18c90 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
18ca0 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
18cb0 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
18cc0 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
18cd0 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
18ce0 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
18cf0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
18d00 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
18d10 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
18d20 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
18d30 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
18d40 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
18d50 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
18d60 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
18d70 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
18d80 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
18d90 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
18da0 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
18db0 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
18dc0 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
18dd0 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
18de0 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
18df0 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
18e00 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
18e10 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
18e20 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
18e30 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
18e40 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
18e50 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
18e60 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
18e70 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
18e80 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
18e90 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
18ea0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
18eb0 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
18ec0 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
18ed0 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
18ee0 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
18ef0 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
18f00 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
18f10 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
18f20 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
18f30 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
18f40 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
18f50 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
18f60 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
18f70 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
18f80 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
18f90 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
18fa0 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
18fb0 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
18fc0 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
18fd0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
18fe0 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
18ff0 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
19000 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
19010 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
19020 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
19030 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
19040 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
19050 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
19060 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
19070 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
19080 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
19090 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
190a0 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
190b0 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
190c0 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
190d0 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
190e0 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
190f0 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
19100 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
19110 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
19120 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
19130 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
19140 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
19150 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
19160 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
19170 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66  ** readers.  ^If
19180 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
19190 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
191a0 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
191b0 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
191c0 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
191d0 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
191e0 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
191f0 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
19200 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
19210 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
19220 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
19230 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
19240 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
19250 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
19260 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f    ^This error co
19270 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
19280 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
19290 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
192a0 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
192b0 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
192c0 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  ="/cvstrac/wiki?
192d0 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
192e0 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
192f0 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
19300 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
19310 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
19320 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
19330 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
19340 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a  s important..**.
19350 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
19360 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
19370 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
19380 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
19390 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
193a0 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
193b0 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
193c0 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
193d0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
193e0 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
193f0 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
19400 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
19410 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
19420 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
19430 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
19440 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
19450 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
19460 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
19470 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
19480 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
19490 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
194a0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
194b0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
194c0 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
194d0 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
194e0 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
194f0 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
19500 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
19510 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
19520 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
19530 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
19540 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
19550 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
19560 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c   handler..*/.SQL
19570 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
19580 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72  te3_busy_handler
19590 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a  (sqlite3*, int(*
195a0 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f  )(void*,int), vo
195b0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
195c0 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73  I3REF: Set A Bus
195d0 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20  y Timeout.**.** 
195e0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
195f0 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75  ts a [sqlite3_bu
19600 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73  sy_handler | bus
19610 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20  y handler] that 
19620 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20  sleeps.** for a 
19630 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74  specified amount
19640 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20   of time when a 
19650 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e  table is locked.
19660 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a    ^The handler.*
19670 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c  * will sleep mul
19680 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69  tiple times unti
19690 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20  l at least "ms" 
196a0 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
196b0 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65  sleeping.** have
196c0 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e   accumulated.  ^
196d0 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22  After at least "
196e0 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
196f0 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a   of sleeping,.**
19700 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74   the handler ret
19710 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75  urns 0 which cau
19720 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ses [sqlite3_ste
19730 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a  p()] to return.*
19740 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  * [SQLITE_BUSY] 
19750 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
19760 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a  _BLOCKED]..**.**
19770 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72   ^Calling this r
19780 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61  outine with an a
19790 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61  rgument less tha
197a0 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65  n or equal to ze
197b0 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20  ro.** turns off 
197c0 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  all busy handler
197d0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65  s..**.** ^(There
197e0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73   can only be a s
197f0 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c  ingle busy handl
19800 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  er for a particu
19810 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  lar.** [database
19820 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79   connection] any
19830 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e   any given momen
19840 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62  t.  If another b
19850 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  usy handler.** w
19860 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69  as defined  (usi
19870 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ng [sqlite3_busy
19880 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69  _handler()]) pri
19890 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  or to calling.**
198a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74   this routine, t
198b0 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68  hat other busy h
198c0 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65  andler is cleare
198d0 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  d.)^.*/.SQLITE_A
198e0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
198f0 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69  usy_timeout(sqli
19900 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a  te3*, int ms);..
19910 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19920 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74  Convenience Rout
19930 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67  ines For Running
19940 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54   Queries.**.** T
19950 68 69 73 20 69 73 20 61 20 6c 65 67 61 63 79 20  his is a legacy 
19960 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 69  interface that i
19970 73 20 70 72 65 73 65 72 76 65 64 20 66 6f 72 20  s preserved for 
19980 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
19990 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20  ibility..** Use 
199a0 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  of this interfac
199b0 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65  e is not recomme
199c0 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69  nded..**.** Defi
199d0 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73  nition: A <b>res
199e0 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73  ult table</b> is
199f0 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72   memory data str
19a00 75 63 74 75 72 65 20 63 72 65 61 74 65 64 20 62  ucture created b
19a10 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  y the.** [sqlite
19a20 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69  3_get_table()] i
19a30 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72 65 73  nterface.  A res
19a40 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64  ult table record
19a50 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74  s the.** complet
19a60 65 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 20  e query results 
19a70 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  from one or more
19a80 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20   queries..**.** 
19a90 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70  The table concep
19aa0 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d  tually has a num
19ab0 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20  ber of rows and 
19ac0 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a  columns.  But.**
19ad0 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61   these numbers a
19ae0 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74  re not part of t
19af0 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
19b00 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a  itself.  These.*
19b10 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62  * numbers are ob
19b20 74 61 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c  tained separatel
19b30 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65  y.  Let N be the
19b40 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a   number of rows.
19b50 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20  ** and M be the 
19b60 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
19b70 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c  s..**.** A resul
19b80 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72  t table is an ar
19b90 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
19ba0 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  to zero-terminat
19bb0 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73  ed UTF-8 strings
19bc0 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28  ..** There are (
19bd0 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20  N+1)*M elements 
19be0 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20 20 54  in the array.  T
19bf0 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74  he first M point
19c00 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20  ers point.** to 
19c10 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
19c20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f  strings that  co
19c30 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  ntain the names 
19c40 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a  of the columns..
19c50 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67  ** The remaining
19c60 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69   entries all poi
19c70 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65 73 75  nt to query resu
19c80 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65  lts.  NULL value
19c90 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e  s result.** in N
19ca0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41  ULL pointers.  A
19cb0 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20  ll other values 
19cc0 61 72 65 20 69 6e 20 74 68 65 69 72 20 55 54 46  are in their UTF
19cd0 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  -8 zero-terminat
19ce0 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70  ed.** string rep
19cf0 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72  resentation as r
19d00 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
19d10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
19d20 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75  )]..**.** A resu
19d30 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63  lt table might c
19d40 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72  onsist of one or
19d50 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c   more memory all
19d60 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20  ocations..** It 
19d70 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70  is not safe to p
19d80 61 73 73 20 61 20 72 65 73 75 6c 74 20 74 61 62  ass a result tab
19d90 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b  le directly to [
19da0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
19db0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
19dc0 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61  le should be dea
19dd0 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b  llocated using [
19de0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
19df0 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41  le()]..**.** ^(A
19e00 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20  s an example of 
19e10 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65  the result table
19e20 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65   format, suppose
19e30 20 61 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a   a query result.
19e40 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ** is as follows
19e50 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
19e60 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
19e70 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20      Name        
19e80 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20  | Age.**        
19e90 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
19ea0 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20  -------.**      
19eb0 20 20 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20    Alice       | 
19ec0 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62  43.**        Bob
19ed0 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a           | 28.**
19ee0 20 20 20 20 20 20 20 20 43 69 6e 64 79 20 20 20          Cindy   
19ef0 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72      | 21.** </pr
19f00 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
19f10 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20  **.** There are 
19f20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32  two column (M==2
19f30 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73  ) and three rows
19f40 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74   (N==3).  Thus t
19f50 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62  he.** result tab
19f60 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69 65 73  le has 8 entries
19f70 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65 20 72  .  Suppose the r
19f80 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73  esult table is s
19f90 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61  tored.** in an a
19fa0 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73  rray names azRes
19fb0 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73  ult.  Then azRes
19fc0 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63  ult holds this c
19fd0 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ontent:.**.** <b
19fe0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
19ff0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a000 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d  lt&#91;0] = "Nam
1a010 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1a020 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20  Result&#91;1] = 
1a030 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Age";.**       
1a040 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d   azResult&#91;2]
1a050 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20   = "Alice";.**  
1a060 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a070 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a  91;3] = "43";.**
1a080 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a090 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b  &#91;4] = "Bob";
1a0a0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1a0b0 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38  ult&#91;5] = "28
1a0c0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a0d0 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22  esult&#91;6] = "
1a0e0 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20  Cindy";.**      
1a0f0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37    azResult&#91;7
1a100 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70  ] = "21";.** </p
1a110 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1a120 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
1a130 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a140 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75  ) function evalu
1a150 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  ates one or more
1a160 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
1a170 70 61 72 61 74 65 64 20 53 51 4c 20 73 74 61 74  parated SQL stat
1a180 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65  ements in the ze
1a190 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1a1a0 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66  F-8.** string of
1a1b0 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74   its 2nd paramet
1a1c0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  er and returns a
1a1d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f   result table to
1a1e0 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   the.** pointer 
1a1f0 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64  given in its 3rd
1a200 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
1a210 2a 20 41 66 74 65 72 20 74 68 65 20 61 70 70 6c  * After the appl
1a220 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69  ication has fini
1a230 73 68 65 64 20 77 69 74 68 20 74 68 65 20 72 65  shed with the re
1a240 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65  sult from sqlite
1a250 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a  3_get_table(),.*
1a260 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73 20 74  * it must pass t
1a270 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1a280 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74  pointer to sqlit
1a290 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20  e3_free_table() 
1a2a0 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72  in order to.** r
1a2b0 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72  elease the memor
1a2c0 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f  y that was mallo
1a2d0 63 65 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66  ced.  Because of
1a2e0 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20   the way the.** 
1a2f0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1a300 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74 68 69  )] happens withi
1a310 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  n sqlite3_get_ta
1a320 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69  ble(), the calli
1a330 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  ng.** function m
1a340 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63  ust not try to c
1a350 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  all [sqlite3_fre
1a360 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20  e()] directly.  
1a370 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  Only.** [sqlite3
1a380 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69  _free_table()] i
1a390 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73  s able to releas
1a3a0 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
1a3b0 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79  perly and safely
1a3c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
1a3d0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1a3e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6d 70  interface is imp
1a3f0 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72  lemented as a wr
1a400 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20  apper around.** 
1a410 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1a420 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  .  The sqlite3_g
1a430 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69  et_table() routi
1a440 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  ne does not have
1a450 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e   access.** to an
1a460 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20  y internal data 
1a470 73 74 72 75 63 74 75 72 65 73 20 6f 66 20 53 51  structures of SQ
1a480 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f  Lite.  It uses o
1a490 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a  nly the public.*
1a4a0 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65 66 69  * interface defi
1a4b0 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20 61 20  ned here.  As a 
1a4c0 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72  consequence, err
1a4d0 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72 20 69  ors that occur i
1a4e0 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72  n the.** wrapper
1a4f0 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f   layer outside o
1a500 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b  f the internal [
1a510 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
1a520 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  call are not.** 
1a530 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62  reflected in sub
1a540 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
1a550 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64   [sqlite3_errcod
1a560 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  e()] or.** [sqli
1a570 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a  te3_errmsg()]..*
1a580 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1a590 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1a5a0 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
1a5b0 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
1a5c0 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
1a5d0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1a5e0 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
1a5f0 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
1a600 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
1a610 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
1a620 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
1a630 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
1a640 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
1a650 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1a660 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
1a670 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
1a680 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
1a690 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1a6a0 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
1a6b0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
1a6c0 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
1a6d0 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
1a6e0 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
1a6f0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
1a700 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
1a710 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
1a720 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
1a730 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
1a740 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
1a750 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1a760 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1a770 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
1a780 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
1a790 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
1a7a0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
1a7b0 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
1a7c0 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ibrary..**.** ^T
1a7d0 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
1a7e0 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
1a7f0 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
1a800 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
1a810 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
1a820 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
1a830 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
1a840 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
1a850 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
1a860 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
1a870 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
1a880 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
1a890 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a8a0 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
1a8b0 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
1a8c0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
1a8d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1a8e0 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
1a8f0 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
1a900 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
1a910 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
1a920 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
1a930 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
1a940 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
1a950 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
1a960 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
1a970 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
1a980 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
1a990 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
1a9a0 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
1a9b0 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
1a9c0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1a9d0 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
1a9e0 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
1a9f0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
1aa00 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
1aa10 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
1aa20 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
1aa30 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
1aa40 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
1aa50 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
1aa60 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
1aa70 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
1aa80 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
1aa90 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
1aaa0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
1aab0 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
1aac0 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
1aad0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1aae0 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
1aaf0 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
1ab00 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
1ab10 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
1ab20 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
1ab30 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
1ab40 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
1ab50 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
1ab60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
1ab70 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
1ab80 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
1ab90 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
1aba0 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
1abb0 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
1abc0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1abd0 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
1abe0 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
1abf0 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
1ac00 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
1ac10 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
1ac20 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
1ac30 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
1ac40 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
1ac50 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
1ac60 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
1ac70 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
1ac80 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
1ac90 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
1aca0 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
1acb0 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
1acc0 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
1acd0 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
1ace0 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
1acf0 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
1ad00 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
1ad10 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
1ad20 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
1ad30 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
1ad40 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
1ad50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
1ad60 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1ad70 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
1ad80 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
1ad90 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
1ada0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1adb0 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
1adc0 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
1add0 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
1ade0 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
1adf0 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
1ae00 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
1ae10 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
1ae20 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
1ae30 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
1ae40 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
1ae50 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
1ae60 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
1ae70 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
1ae80 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
1ae90 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e   ^(The %q option
1aea0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
1aeb0 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
1aec0 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d  tutes a nul-term
1aed0 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1aee0 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65   from the argume
1aef0 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71  nt list.  But %q
1af00 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76   also doubles ev
1af10 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63 74  ery '\'' charact
1af20 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73  er..** %q is des
1af30 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e  igned for use in
1af40 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69  side a string li
1af50 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75  teral.)^  By dou
1af60 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a  bling each '\''.
1af70 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74 20  ** character it 
1af80 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68 61  escapes that cha
1af90 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77  racter and allow
1afa0 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72  s it to be inser
1afb0 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20  ted into.** the 
1afc0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f  string..**.** Fo
1afd0 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d  r example, assum
1afe0 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61 72  e the string var
1aff0 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74  iable zText cont
1b000 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c  ains text as fol
1b010 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1b020 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1b030 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20    char *zText = 
1b040 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  "It's a happy da
1b050 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  y!";.** </pre></
1b060 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1b070 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68  * One can use th
1b080 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51  is text in an SQ
1b090 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66  L statement as f
1b0a0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1b0b0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1b0c0 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d  **  char *zSQL =
1b0d0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1b0e0 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61  ("INSERT INTO ta
1b0f0 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27 29  ble VALUES('%q')
1b100 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1b110 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1b120 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1b130 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1b140 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1b150 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b160 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
1b170 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e   %q format strin
1b180 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20 27  g is used, the '
1b190 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69 6e  \'' character in
1b1a0 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63   zText.** is esc
1b1b0 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c  aped and the SQL
1b1c0 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61 73   generated is as
1b1d0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1b1e0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b1f0 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1b200 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1b210 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20 64  'It''s a happy d
1b220 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!').** </pre><
1b230 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1b240 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72 65  ** This is corre
1b250 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65 64  ct.  Had we used
1b260 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25   %s instead of %
1b270 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65 64  q, the generated
1b280 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61   SQL.** would ha
1b290 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74  ve looked like t
1b2a0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  his:.**.** <bloc
1b2b0 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1b2c0 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62   INSERT INTO tab
1b2d0 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 73  le1 VALUES('It's
1b2e0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 3b   a happy day!');
1b2f0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1b300 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1b310 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c  is second exampl
1b320 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74  e is an SQL synt
1b330 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20  ax error.  As a 
1b340 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75  general rule you
1b350 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79   should.** alway
1b360 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61 64  s use %q instead
1b370 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65   of %s when inse
1b380 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20  rting text into 
1b390 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  a string literal
1b3a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51  ..**.** ^(The %Q
1b3b0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1b3c0 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74 20  ke %q except it 
1b3d0 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65  also adds single
1b3e0 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a   quotes around.*
1b3f0 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66  * the outside of
1b400 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e   the total strin
1b410 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  g.  Additionally
1b420 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  , if the paramet
1b430 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67  er in the.** arg
1b440 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20  ument list is a 
1b450 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51  NULL pointer, %Q
1b460 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68 65   substitutes the
1b470 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69   text "NULL" (wi
1b480 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20  thout.** single 
1b490 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20  quotes).)^  So, 
1b4a0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65  for example, one
1b4b0 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a   could say:.**.*
1b4c0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1b4d0 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1b4e0 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1b4f0 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1b500 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25  O table VALUES(%
1b510 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  Q)", zText);.** 
1b520 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1b530 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1b540 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1b550 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1b560 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1b570 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
1b580 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65  above will rende
1b590 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20  r a correct SQL 
1b5a0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
1b5b0 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c   zSQL.** variabl
1b5c0 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54  e even if the zT
1b5d0 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73 20  ext variable is 
1b5e0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
1b5f0 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22  **.** ^(The "%z"
1b600 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69   formatting opti
1b610 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25  on works like "%
1b620 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65 0a  s" but with the.
1b630 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  ** addition that
1b640 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69 6e   after the strin
1b650 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64 20  g has been read 
1b660 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a  and copied into.
1b670 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b  ** the result, [
1b680 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1b690 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65  is called on the
1b6a0 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e   input string.)^
1b6b0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
1b6c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72  har *sqlite3_mpr
1b6d0 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a  intf(const char*
1b6e0 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,...);.SQLITE_AP
1b6f0 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1b700 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  vmprintf(const c
1b710 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1b720 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20  SQLITE_API char 
1b730 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
1b740 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1b750 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53  t char*, ...);.S
1b760 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a  QLITE_API char *
1b770 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1b780 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
1b790 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74  t char*, va_list
1b7a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b7b0 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  EF: Memory Alloc
1b7c0 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a  ation Subsystem.
1b7d0 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  **.** The SQLite
1b7e0 20 63 6f 72 65 20 75 73 65 73 20 74 68 65 73 65   core uses these
1b7f0 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20   three routines 
1b800 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f  for all of its o
1b810 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d  wn.** internal m
1b820 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1b830 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69   needs. "Core" i
1b840 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  n the previous s
1b850 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20  entence.** does 
1b860 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72  not include oper
1b870 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
1b880 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d  cific VFS implem
1b890 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a  entation.  The.*
1b8a0 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73  * Windows VFS us
1b8b0 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63  es native malloc
1b8c0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f  () and free() fo
1b8d0 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e  r some operation
1b8e0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
1b8f0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1b900 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
1b910 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c   pointer to a bl
1b920 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  ock.** of memory
1b930 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1b940 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65  s in length, whe
1b950 72 65 20 4e 20 69 73 20 74 68 65 20 70 61 72 61  re N is the para
1b960 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71  meter..** ^If sq
1b970 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1b980 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61  s unable to obta
1b990 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20 66 72  in sufficient fr
1b9a0 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74  ee.** memory, it
1b9b0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
1b9c0 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68  pointer.  ^If th
1b9d0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f  e parameter N to
1b9e0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1b9f0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20  oc() is zero or 
1ba00 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 73 71  negative then sq
1ba10 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72  lite3_malloc() r
1ba20 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c  eturns.** a NULL
1ba30 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1ba40 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33  ^Calling sqlite3
1ba50 5f 66 72 65 65 28 29 20 77 69 74 68 20 61 20 70  _free() with a p
1ba60 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c  ointer previousl
1ba70 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  y returned.** by
1ba80 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1ba90 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1baa0 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20  lloc() releases 
1bab0 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a  that memory so.*
1bac0 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68 74 20  * that it might 
1bad0 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65  be reused.  ^The
1bae0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1baf0 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20  routine is.** a 
1bb00 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c  no-op if is call
1bb10 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
1bb20 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67  ointer.  Passing
1bb30 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
1bb40 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  ** to sqlite3_fr
1bb50 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73  ee() is harmless
1bb60 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67 20 66  .  After being f
1bb70 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20  reed, memory.** 
1bb80 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62  should neither b
1bb90 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74  e read nor writt
1bba0 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e  en.  Even readin
1bbb0 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65  g previously fre
1bbc0 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67  ed.** memory mig
1bbd0 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73  ht result in a s
1bbe0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1bbf0 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  t or other sever
1bc00 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f  e error..** Memo
1bc10 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61  ry corruption, a
1bc20 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1bc30 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65  ult, or other se
1bc40 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69  vere error.** mi
1bc50 67 68 74 20 72 65 73 75 6c 74 20 69 66 20 73 71  ght result if sq
1bc60 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20  lite3_free() is 
1bc70 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f  called with a no
1bc80 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  n-NULL pointer t
1bc90 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f  hat.** was not o
1bca0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c  btained from sql
1bcb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
1bcc0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1bcd0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ()..**.** ^(The 
1bce0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1bcf0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
1bd00 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61  mpts to resize a
1bd10 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79  .** prior memory
1bd20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
1bd30 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  e at least N byt
1bd40 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  es, where N is t
1bd50 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1bd60 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d  ameter.  The mem
1bd70 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
1bd80 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69 73 20  o be resized is 
1bd90 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  the first.** par
1bda0 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74  ameter.)^ ^ If t
1bdb0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
1bdc0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1bdd0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20  alloc().** is a 
1bde0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
1bdf0 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72 20 69  n its behavior i
1be00 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63  s identical to c
1be10 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
1be20 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72  3_malloc(N) wher
1be30 65 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e  e N is the secon
1be40 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1be50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1be60 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63  ..** ^If the sec
1be70 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1be80 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1be90 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a  () is zero or.**
1bea0 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 74   negative then t
1beb0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 65  he behavior is e
1bec0 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20  xactly the same 
1bed0 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  as calling.** sq
1bee0 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20 77 68  lite3_free(P) wh
1bef0 65 72 65 20 50 20 69 73 20 74 68 65 20 66 69 72  ere P is the fir
1bf00 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1bf10 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1bf20 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72  )..** ^sqlite3_r
1bf30 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
1bf40 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1bf50 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1bf60 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  n.** of at least
1bf70 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
1bf80 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66   or NULL if suff
1bf90 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73  icient memory is
1bfa0 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a   unavailable..**
1bfb0 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20 73 69   ^If M is the si
1bfc0 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ze of the prior 
1bfd0 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e  allocation, then
1bfe0 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a   min(N,M) bytes.
1bff0 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20  ** of the prior 
1c000 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63  allocation are c
1c010 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62  opied into the b
1c020 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66  eginning of buff
1c030 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  er returned.** b
1c040 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  y sqlite3_reallo
1c050 63 28 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f  c() and the prio
1c060 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  r allocation is 
1c070 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71  freed..** ^If sq
1c080 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1c090 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68  returns NULL, th
1c0a0 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  en the prior all
1c0b0 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f  ocation.** is no
1c0c0 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  t freed..**.** ^
1c0d0 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72  The memory retur
1c0e0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d  ned by sqlite3_m
1c0f0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69  alloc() and sqli
1c100 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a  te3_realloc().**
1c110 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e   is always align
1c120 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61  ed to at least a
1c130 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8 byte boundar
1c140 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20  y, or to a.** 4 
1c150 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66  byte boundary if
1c160 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42   the [SQLITE_4_B
1c170 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c  YTE_ALIGNED_MALL
1c180 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  OC] compile-time
1c190 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73  .** option is us
1c1a0 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c  ed..**.** In SQL
1c1b0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e  ite version 3.5.
1c1c0 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20  0 and 3.5.1, it 
1c1d0 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  was possible to 
1c1e0 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51  define.** the SQ
1c1f0 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59  LITE_OMIT_MEMORY
1c200 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63  _ALLOCATION whic
1c210 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68  h would cause th
1c220 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d  e built-in.** im
1c230 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1c240 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74  these routines t
1c250 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54  o be omitted.  T
1c260 68 61 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a  hat capability.*
1c270 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70  * is no longer p
1c280 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62  rovided.  Only b
1c290 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
1c2a0 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65  llocators can be
1c2b0 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69   used..**.** Pri
1c2c0 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72  or to SQLite ver
1c2d0 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65  sion 3.7.10, the
1c2e0 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65   Windows OS inte
1c2f0 72 66 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c  rface layer call
1c300 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d  ed.** the system
1c310 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1c320 65 65 28 29 20 64 69 72 65 63 74 6c 79 20 77 68  ee() directly wh
1c330 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a  en converting.**
1c340 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65   filenames betwe
1c350 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63  en the UTF-8 enc
1c360 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20 53 51  oding used by SQ
1c370 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74  Lite.** and what
1c380 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e  ever filename en
1c390 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 20 62  coding is used b
1c3a0 79 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72  y the particular
1c3b0 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74   Windows.** inst
1c3c0 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72  allation.  Memor
1c3d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
1c3e0 6f 72 73 20 77 65 72 65 20 64 65 74 65 63 74 65  ors were detecte
1c3f0 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77  d, but.** they w
1c400 65 72 65 20 72 65 70 6f 72 74 65 64 20 62 61 63  ere reported bac
1c410 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e  k as [SQLITE_CAN
1c420 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51  TOPEN] or.** [SQ
1c430 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68  LITE_IOERR] rath
1c440 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
1c450 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  NOMEM]..**.** Th
1c460 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65  e pointer argume
1c470 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  nts to [sqlite3_
1c480 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  free()] and [sql
1c490 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1c4a0 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  ** must be eithe
1c4b0 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70  r NULL or else p
1c4c0 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64  ointers obtained
1c4d0 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a   from a prior.**
1c4e0 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b   invocation of [
1c4f0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c500 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1c510 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61  alloc()] that ha
1c520 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65  ve.** not yet be
1c530 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a  en released..**.
1c540 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
1c550 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64  on must not read
1c560 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20 70 61   or write any pa
1c570 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b  rt of.** a block
1c580 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72   of memory after
1c590 20 69 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c   it has been rel
1c5a0 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b  eased using.** [
1c5b0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1c5c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1c5d0 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  loc()]..*/.SQLIT
1c5e0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1c5f0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1c600 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1c610 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
1c620 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53  c(void*, int);.S
1c630 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1c640 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64  qlite3_free(void
1c650 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1c660 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
1c670 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63 73  cator Statistics
1c680 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72  .**.** SQLite pr
1c690 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77 6f  ovides these two
1c6a0 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20   interfaces for 
1c6b0 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65  reporting on the
1c6c0 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68   status.** of th
1c6d0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  e [sqlite3_mallo
1c6e0 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66  c()], [sqlite3_f
1c6f0 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ree()], and [sql
1c700 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a  ite3_realloc()].
1c710 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69  ** routines, whi
1c720 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c  ch form the buil
1c730 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
1c740 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
1c750 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
1c760 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1c770 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  d()] routine ret
1c780 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1c790 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d  of bytes.** of m
1c7a0 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20  emory currently 
1c7b0 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c  outstanding (mal
1c7c0 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72  loced but not fr
1c7d0 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73  eed)..** ^The [s
1c7e0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1c7f0 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69  ghwater()] routi
1c800 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d  ne returns the m
1c810 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20  aximum.** value 
1c820 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  of [sqlite3_memo
1c830 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65  ry_used()] since
1c840 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20   the high-water 
1c850 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74  mark.** was last
1c860 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61   reset.  ^The va
1c870 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
1c880 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1c890 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20  _used()] and.** 
1c8a0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1c8b0 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63  highwater()] inc
1c8c0 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61  lude any overhea
1c8d0 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51  d.** added by SQ
1c8e0 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c  Lite in its impl
1c8f0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73  ementation of [s
1c900 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1c910 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65  ,.** but not ove
1c920 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20 74  rhead added by t
1c930 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e  he any underlyin
1c940 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  g system library
1c950 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61  .** routines tha
1c960 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  t [sqlite3_mallo
1c970 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a  c()] may call..*
1c980 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79  *.** ^The memory
1c990 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1c9a0 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68 65   is reset to the
1c9b0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
1c9c0 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  f.** [sqlite3_me
1c9d0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20  mory_used()] if 
1c9e0 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20  and only if the 
1c9f0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
1ca00 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1ca10 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73 20  highwater()] is 
1ca20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75  true.  ^The valu
1ca30 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79  e returned.** by
1ca40 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1ca50 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20 69  _highwater(1)] i
1ca60 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  s the high-water
1ca70 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74   mark.** prior t
1ca80 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a  o the reset..*/.
1ca90 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
1caa0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1cab0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1cac0 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  d);.SQLITE_API s
1cad0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1cae0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1caf0 77 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46  water(int resetF
1cb00 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  lag);../*.** CAP
1cb10 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61  I3REF: Pseudo-Ra
1cb20 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65  ndom Number Gene
1cb30 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  rator.**.** SQLi
1cb40 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69  te contains a hi
1cb50 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64  gh-quality pseud
1cb60 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20  o-random number 
1cb70 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29  generator (PRNG)
1cb80 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65   used to.** sele
1cb90 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44  ct random [ROWID
1cba0 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20   | ROWIDs] when 
1cbb0 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65  inserting new re
1cbc0 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62  cords into a tab
1cbd0 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61  le that.** alrea
1cbe0 64 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67  dy uses the larg
1cbf0 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f  est possible [RO
1cc00 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20  WID].  The PRNG 
1cc10 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72  is also used for
1cc20 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e  .** the build-in
1cc30 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61   random() and ra
1cc40 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66  ndomblob() SQL f
1cc50 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20  unctions.  This 
1cc60 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
1cc70 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
1cc80 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73   to access the s
1cc90 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68  ame PRNG for oth
1cca0 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a  er purposes..**.
1ccb0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68  ** ^A call to th
1ccc0 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65  is routine store
1ccd0 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e  s N bytes of ran
1cce0 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66  domness into buf
1ccf0 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fer P..**.** ^Th
1cd00 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69  e first time thi
1cd10 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76  s routine is inv
1cd20 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74  oked (either int
1cd30 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a  ernally or by.**
1cd40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
1cd50 29 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65  ) the PRNG is se
1cd60 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f  eded using rando
1cd70 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mness obtained.*
1cd80 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64  * from the xRand
1cd90 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66  omness method of
1cda0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
1cdb0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
1cdc0 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75  t..** ^On all su
1cdd0 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74  bsequent invocat
1cde0 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f  ions, the pseudo
1cdf0 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67  -randomness is g
1ce00 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65  enerated.** inte
1ce10 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f  rnally and witho
1ce20 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74  ut recourse to t
1ce30 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  he [sqlite3_vfs]
1ce40 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20   xRandomness.** 
1ce50 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54  method..*/.SQLIT
1ce60 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1ce70 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
1ce80 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
1ce90 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1cea0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
1ceb0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
1cec0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
1ced0 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
1cee0 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
1cef0 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
1cf00 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
1cf10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1cf20 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
1cf30 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
1cf40 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
1cf50 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1cf60 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
1cf70 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
1cf80 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
1cf90 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1cfa0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
1cfb0 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
1cfc0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1cfd0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
1cfe0 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
1cff0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1d000 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
1d010 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
1d020 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
1d030 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
1d040 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
1d050 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
1d060 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
1d070 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
1d080 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1d090 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
1d0a0 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
1d0b0 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
1d0c0 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
1d0d0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d0e0 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
1d0f0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
1d100 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
1d110 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
1d120 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
1d130 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
1d140 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
1d150 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1d160 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
1d170 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
1d180 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
1d190 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
1d1a0 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
1d1b0 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
1d1c0 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
1d1d0 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
1d1e0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1d1f0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
1d200 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
1d210 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1d220 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
1d230 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
1d240 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
1d250 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d260 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
1d270 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
1d280 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
1d290 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
1d2a0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
1d2b0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
1d2c0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1d2d0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1d2e0 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
1d2f0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
1d300 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
1d310 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
1d320 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1d330 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
1d340 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1d350 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
1d360 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
1d370 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
1d380 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
1d390 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
1d3a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
1d3b0 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
1d3c0 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
1d3d0 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
1d3e0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1d3f0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
1d400 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
1d410 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
1d420 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
1d430 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
1d440 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
1d450 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
1d460 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
1d470 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
1d480 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
1d490 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
1d4a0 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
1d4b0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
1d4c0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
1d4d0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
1d4e0 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
1d4f0 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
1d500 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
1d510 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
1d520 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1d530 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
1d540 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
1d550 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
1d560 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
1d570 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
1d580 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
1d590 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
1d5a0 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
1d5b0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
1d5c0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
1d5d0 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
1d5e0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
1d5f0 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
1d600 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
1d610 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
1d620 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
1d630 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
1d640 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
1d650 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
1d660 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
1d670 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
1d680 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
1d690 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
1d6a0 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
1d6b0 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
1d6c0 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
1d6d0 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
1d6e0 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
1d6f0 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
1d700 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1d710 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
1d720 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
1d730 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1d740 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
1d750 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
1d760 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
1d770 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
1d780 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
1d790 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
1d7a0 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
1d7b0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
1d7c0 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
1d7d0 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
1d7e0 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
1d7f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1d800 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
1d810 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
1d820 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
1d830 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
1d840 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
1d850 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
1d860 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
1d870 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
1d880 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
1d890 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
1d8a0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
1d8b0 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
1d8c0 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
1d8d0 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
1d8e0 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
1d8f0 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
1d900 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
1d910 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
1d920 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
1d930 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
1d940 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
1d950 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
1d960 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1d970 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
1d980 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
1d990 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
1d9a0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
1d9b0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1d9c0 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
1d9d0 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
1d9e0 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
1d9f0 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
1da00 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
1da10 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1da20 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
1da30 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
1da40 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
1da50 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
1da60 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
1da70 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1da80 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
1da90 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
1daa0 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
1dab0 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
1dac0 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
1dad0 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
1dae0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1daf0 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
1db00 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
1db10 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
1db20 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1db30 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
1db40 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
1db50 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
1db60 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
1db70 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
1db80 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
1db90 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
1dba0 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
1dbb0 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
1dbc0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
1dbd0 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
1dbe0 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
1dbf0 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
1dc00 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
1dc10 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
1dc20 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
1dc30 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
1dc40 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
1dc50 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
1dc60 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1dc70 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1dc80 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1dc90 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1dca0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1dcb0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1dcc0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
1dcd0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1dce0 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
1dcf0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1dd00 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1dd10 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1dd20 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1dd30 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1dd40 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1dd50 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1dd60 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1dd70 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
1dd80 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1dd90 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
1dda0 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
1ddb0 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
1ddc0 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
1ddd0 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
1dde0 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
1ddf0 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
1de00 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
1de10 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
1de20 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
1de30 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1de40 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
1de50 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1de60 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
1de70 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
1de80 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1de90 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
1dea0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1deb0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1dec0 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
1ded0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1dee0 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1def0 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
1df00 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
1df10 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
1df20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
1df30 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
1df40 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
1df50 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
1df60 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
1df70 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
1df80 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
1df90 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
1dfa0 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
1dfb0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1dfc0 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
1dfd0 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54  change..*/.SQLIT
1dfe0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1dff0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1e000 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20  (.  sqlite3*,.  
1e010 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69  int (*xAuth)(voi
1e020 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61  d*,int,const cha
1e030 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
1e040 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74  onst char*,const
1e050 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20   char*),.  void 
1e060 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f  *pUserData.);../
1e070 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
1e080 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e  uthorizer Return
1e090 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
1e0a0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
1e0b0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
1e0c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  rizer callback f
1e0d0 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a  unction] must.**
1e0e0 20 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b   return either [
1e0f0 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e  SQLITE_OK] or on
1e100 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63  e of these two c
1e110 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65  onstants in orde
1e120 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53  r.** to signal S
1e130 51 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72  QLite whether or
1e140 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20   not the action 
1e150 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53  is permitted.  S
1e160 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ee the.** [sqlit
1e170 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e180 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64  r | authorizer d
1e190 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f  ocumentation] fo
1e1a0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
1e1b0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
1e1c0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
1e1d0 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c  ITE_IGNORE is al
1e1e0 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51  so used as a [SQ
1e1f0 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20  LITE_ROLLBACK | 
1e200 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20  return code].** 
1e210 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
1e220 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69  3_vtab_on_confli
1e230 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ct()] interface.
1e240 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
1e250 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a  TE_DENY   1   /*
1e260 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73   Abort the SQL s
1e270 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e  tatement with an
1e280 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e   error */.#defin
1e290 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  e SQLITE_IGNORE 
1e2a0 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c  2   /* Don't all
1e2b0 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64  ow access, but d
1e2c0 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e  on't generate an
1e2d0 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   error */../*.**
1e2e0 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f   CAPI3REF: Autho
1e2f0 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64  rizer Action Cod
1e300 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71  es.**.** The [sq
1e310 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1e320 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  izer()] interfac
1e330 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61  e registers a ca
1e340 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a  llback function.
1e350 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b  ** that is invok
1e360 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20  ed to authorize 
1e370 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74  certain SQL stat
1e380 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20  ement actions.  
1e390 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
1e3a0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
1e3b0 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e  allback is an in
1e3c0 74 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20  teger code that 
1e3d0 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61  specifies.** wha
1e3e0 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e  t action is bein
1e3f0 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  g authorized.  T
1e400 68 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74  hese are the int
1e410 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65  eger action code
1e420 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75  s that.** the au
1e430 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e440 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e  k may be passed.
1e450 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74  .**.** These act
1e460 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20  ion code values 
1e470 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e  signify what kin
1e480 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69  d of operation i
1e490 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f  s to be.** autho
1e4a0 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20  rized.  The 3rd 
1e4b0 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65  and 4th paramete
1e4c0 72 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  rs to the author
1e4d0 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  ization.** callb
1e4e0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c  ack function wil
1e4f0 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20  l be parameters 
1e500 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e  or NULL dependin
1e510 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68  g on which of th
1e520 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20  ese.** codes is 
1e530 75 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f  used as the seco
1e540 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
1e550 28 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (The 5th paramet
1e560 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74  er to the.** aut
1e570 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e580 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
1e590 74 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d  the database ("m
1e5a0 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a  ain", "temp",.**
1e5b0 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63   etc.) if applic
1e5c0 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74  able.)^  ^The 6t
1e5d0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1e5e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1e5f0 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65  llback.** is the
1e600 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e   name of the inn
1e610 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20  er-most trigger 
1e620 6f 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20  or view that is 
1e630 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a  responsible for.
1e640 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74  ** the access at
1e650 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66  tempt or NULL if
1e660 20 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74   this access att
1e670 65 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79  empt is directly
1e680 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76   from.** top-lev
1e690 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a  el SQL code..*/.
1e6a0 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
1e6b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1e6c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64  ************ 3rd
1e6d0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74   ************ 4t
1e6e0 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23  h ***********/.#
1e6f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1e700 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20  EATE_INDEX      
1e710 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78      1   /* Index
1e720 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1e730 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1e740 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1e750 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20  ATE_TABLE       
1e760 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20     2   /* Table 
1e770 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1e780 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1e790 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1e7a0 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20  TE_TEMP_INDEX   
1e7b0 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    3   /* Index N
1e7c0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1e7d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1e7e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1e7f0 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20  E_TEMP_TABLE    
1e800 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   4   /* Table Na
1e810 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1e820 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1e830 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1e840 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20  _TEMP_TRIGGER   
1e850 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  5   /* Trigger N
1e860 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1e870 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1e880 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1e890 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36  TEMP_VIEW      6
1e8a0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1e8b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1e8c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1e8d0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1e8e0 52 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20  RIGGER        7 
1e8f0 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1e900 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1e910 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1e920 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49  SQLITE_CREATE_VI
1e930 45 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20  EW           8  
1e940 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1e950 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1e960 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1e970 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20  QLITE_DELETE    
1e980 20 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20              9   
1e990 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1e9a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1e9b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1e9c0 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20  LITE_DROP_INDEX 
1e9d0 20 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f            10   /
1e9e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1e9f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1ea00 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ea10 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20  ITE_DROP_TABLE  
1ea20 20 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a           11   /*
1ea30 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1ea40 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ea50 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ea60 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44  TE_DROP_TEMP_IND
1ea70 45 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20  EX      12   /* 
1ea80 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1ea90 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1eaa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1eab0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c  E_DROP_TEMP_TABL
1eac0 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54  E      13   /* T
1ead0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1eae0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1eaf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1eb00 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47  _DROP_TEMP_TRIGG
1eb10 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72  ER    14   /* Tr
1eb20 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1eb30 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1eb40 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1eb50 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20  DROP_TEMP_VIEW  
1eb60 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65       15   /* Vie
1eb70 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1eb80 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1eb90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1eba0 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20  ROP_TRIGGER     
1ebb0 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67      16   /* Trig
1ebc0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1ebd0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1ebe0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1ebf0 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  OP_VIEW         
1ec00 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20     17   /* View 
1ec10 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1ec20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1ec30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53  efine SQLITE_INS
1ec40 45 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20  ERT             
1ec50 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    18   /* Table 
1ec60 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1ec70 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ec80 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47  fine SQLITE_PRAG
1ec90 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MA              
1eca0 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20   19   /* Pragma 
1ecb0 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67  Name     1st arg
1ecc0 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66   or NULL */.#def
1ecd0 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20  ine SQLITE_READ 
1ece0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1ecf0 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  20   /* Table Na
1ed00 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e  me      Column N
1ed10 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1ed20 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54  ne SQLITE_SELECT
1ed30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1ed40 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
1ed50 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
1ed60 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ed70 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43  e SQLITE_TRANSAC
1ed80 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32  TION          22
1ed90 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
1eda0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1edb0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1edc0 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20   SQLITE_UPDATE  
1edd0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20               23 
1ede0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1edf0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1ee00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ee10 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20  SQLITE_ATTACH   
1ee20 20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20              24  
1ee30 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20   /* Filename    
1ee40 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1ee50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ee60 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20  QLITE_DETACH    
1ee70 20 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20             25   
1ee80 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65  /* Database Name
1ee90 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1eea0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1eeb0 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45  LITE_ALTER_TABLE
1eec0 20 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f            26   /
1eed0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1eee0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1eef0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1ef00 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20  ITE_REINDEX     
1ef10 20 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a           27   /*
1ef20 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1ef30 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ef40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ef50 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20  TE_ANALYZE      
1ef60 20 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20          28   /* 
1ef70 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ef80 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ef90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1efa0 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20  E_CREATE_VTABLE 
1efb0 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54         29   /* T
1efc0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d  able Name      M
1efd0 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a  odule Name     *
1efe0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1eff0 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20  _DROP_VTABLE    
1f000 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61        30   /* Ta
1f010 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1f020 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1f030 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f040 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20  FUNCTION        
1f050 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c       31   /* NUL
1f060 4c 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e  L            Fun
1f070 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a  ction Name   */.
1f080 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1f090 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20  AVEPOINT        
1f0a0 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72      32   /* Oper
1f0b0 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65  ation       Save
1f0c0 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23  point Name  */.#
1f0d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
1f0e0 50 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20  PY              
1f0f0 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f      0   /* No lo
1f100 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a  nger used */../*
1f110 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72  .** CAPI3REF: Tr
1f120 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c  acing And Profil
1f130 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ing Functions.**
1f140 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
1f150 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c  es register call
1f160 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74  back functions t
1f170 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  hat can be used 
1f180 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61  for.** tracing a
1f190 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65  nd profiling the
1f1a0 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51   execution of SQ
1f1b0 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
1f1c0 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1f1d0 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1f1e0 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1f1f0 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f  _trace() is invo
1f200 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75  ked at.** variou
1f210 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20  s times when an 
1f220 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73  SQL statement is
1f230 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73   being run by [s
1f240 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
1f250 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1f260 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1f270 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
1f280 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69   a UTF-8 renderi
1f290 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c  ng of the.** SQL
1f2a0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
1f2b0 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  as the statement
1f2c0 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78   first begins ex
1f2d0 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64  ecuting..** ^(Ad
1f2e0 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33  ditional sqlite3
1f2f0 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1f300 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ks might occur.*
1f310 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65  * as each trigge
1f320 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69  red subprogram i
1f330 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20  s entered.  The 
1f340 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72  callbacks for tr
1f350 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69  iggers.** contai
1f360 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f  n a UTF-8 SQL co
1f370 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74  mment that ident
1f380 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65  ifies the trigge
1f390 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  r.)^.**.** The [
1f3a0 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a  SQLITE_TRACE_SIZ
1f3b0 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65  E_LIMIT] compile
1f3c0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e  -time option can
1f3d0 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69   be used to limi
1f3e0 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20  t.** the length 
1f3f0 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65  of [bound parame
1f400 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69  ter] expansion i
1f410 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20  n the output of 
1f420 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e  sqlite3_trace().
1f430 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c  .**.** ^The call
1f440 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65  back function re
1f450 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69  gistered by sqli
1f460 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73  te3_profile() is
1f470 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65   invoked.** as e
1f480 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ach SQL statemen
1f490 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68  t finishes.  ^Th
1f4a0 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1f4b0 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74  ck contains.** t
1f4c0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
1f4d0 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61  ement text and a
1f4e0 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61  n estimate of wa
1f4f0 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a  ll-clock time.**
1f500 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61   of how long tha
1f510 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b  t statement took
1f520 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70   to run.  ^The p
1f530 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a  rofile callback.
1f540 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e  ** time is in un
1f550 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e  its of nanosecon
1f560 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20  ds, however the 
1f570 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
1f580 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c  tation.** is onl
1f590 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c  y capable of mil
1f5a0 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74  lisecond resolut
1f5b0 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c  ion so the six l
1f5c0 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74  east significant
1f5d0 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68  .** digits in th
1f5e0 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69  e time are meani
1f5f0 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20  ngless.  Future 
1f600 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
1f610 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76  te.** might prov
1f620 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73 6f  ide greater reso
1f630 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72  lution on the pr
1f640 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  ofiler callback.
1f650 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33    The.** sqlite3
1f660 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74  _profile() funct
1f670 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65  ion is considere
1f680 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61  d experimental a
1f690 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74  nd is.** subject
1f6a0 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75   to change in fu
1f6b0 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
1f6c0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49   SQLite..*/.SQLI
1f6d0 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
1f6e0 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74  ite3_trace(sqlit
1f6f0 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63  e3*, void(*xTrac
1f700 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
1f710 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53  har*), void*);.S
1f720 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
1f730 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f  _EXPERIMENTAL vo
1f740 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66  id *sqlite3_prof
1f750 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20  ile(sqlite3*,.  
1f760 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29   void(*xProfile)
1f770 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1f780 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36  r*,sqlite3_uint6
1f790 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  4), void*);../*.
1f7a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75 65  ** CAPI3REF: Que
1f7b0 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c  ry Progress Call
1f7c0 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  backs.**.** ^The
1f7d0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1f7e0 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c  s_handler(D,N,X,
1f7f0 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  P) interface cau
1f800 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ses the callback
1f810 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74  .** function X t
1f820 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72  o be invoked per
1f830 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67  iodically during
1f840 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61   long running ca
1f850 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
1f860 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c  e3_exec()], [sql
1f870 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64  ite3_step()] and
1f880 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61   [sqlite3_get_ta
1f890 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61  ble()] for.** da
1f8a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1f8b0 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  n D.  An example
1f8c0 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a   use for this.**
1f8d0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f   interface is to
1f8e0 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64 61   keep a GUI upda
1f8f0 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72  ted during a lar
1f900 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20  ge query..**.** 
1f910 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 50  ^The parameter P
1f920 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f 75   is passed throu
1f930 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  gh as the only p
1f940 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1f950 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1f960 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70  ction X.  ^The p
1f970 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68  arameter N is th
1f980 65 20 61 70 70 72 6f 78 69 6d 61 74 65 20 6e 75  e approximate nu
1f990 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72  mber of .** [vir
1f9a0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73  tual machine ins
1f9b0 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20  tructions] that 
1f9c0 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65  are evaluated be
1f9d0 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65  tween successive
1f9e0 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
1f9f0 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  of the callback 
1fa00 58 2e 20 20 5e 49 66 20 4e 20 69 73 20 6c 65 73  X.  ^If N is les
1fa10 73 20 74 68 61 6e 20 6f 6e 65 20 74 68 65 6e 20  s than one then 
1fa20 74 68 65 20 70 72 6f 67 72 65 73 73 0a 2a 2a 20  the progress.** 
1fa30 68 61 6e 64 6c 65 72 20 69 73 20 64 69 73 61 62  handler is disab
1fa40 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  led..**.** ^Only
1fa50 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
1fa60 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
1fa70 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
1fa80 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
1fa90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1faa0 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
1fab0 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
1fac0 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
1fad0 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
1fae0 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
1faf0 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
1fb00 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
1fb10 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
1fb20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1fb30 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
1fb40 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
1fb50 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
1fb60 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
1fb70 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
1fb80 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1fb90 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
1fba0 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
1fbb0 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
1fbc0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
1fbd0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
1fbe0 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
1fbf0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
1fc00 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
1fc10 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
1fc20 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1fc30 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
1fc40 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
1fc50 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
1fc60 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
1fc70 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
1fc80 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
1fc90 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
1fca0 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
1fcb0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1fcc0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1fcd0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
1fce0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
1fcf0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1fd00 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
1fd10 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
1fd20 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
1fd30 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .**.*/.SQLITE_AP
1fd40 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  I void sqlite3_p
1fd50 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1fd60 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
1fd70 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
1fd80 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
1fd90 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
1fda0 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
1fdb0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
1fdc0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
1fdd0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
1fde0 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
1fdf0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
1fe00 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
1fe10 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
1fe20 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
1fe30 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1fe40 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
1fe50 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
1fe60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1fe70 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
1fe80 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1fe90 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
1fea0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
1feb0 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
1fec0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
1fed0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
1fee0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
1fef0 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
1ff00 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
1ff10 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
1ff20 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
1ff30 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
1ff40 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
1ff50 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
1ff60 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
1ff70 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
1ff80 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
1ff90 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
1ffa0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
1ffb0 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
1ffc0 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
1ffd0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
1ffe0 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
1fff0 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
20000 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
20010 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
20020 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
20030 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
20040 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
20050 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
20060 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
20070 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
20080 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
20090 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
200a0 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
200b0 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
200c0 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
200d0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
200e0 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
200f0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
20100 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
20110 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
20120 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
20130 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
20140 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
20150 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
20160 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
20170 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
20180 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
20190 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
201a0 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
201b0 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
201c0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
201d0 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
201e0 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
201f0 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
20200 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
20210 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
20220 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
20230 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
20240 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
20250 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
20260 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
20270 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
20280 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
20290 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
202a0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
202b0 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
202c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
202d0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
202e0 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
202f0 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
20300 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
20310 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
20320 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
20330 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
20340 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
20350 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
20360 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
20370 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
20380 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
20390 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
203a0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
203b0 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
203c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
203d0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
203e0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
203f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
20400 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
20410 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
20420 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
20430 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
20440 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
20450 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
20460 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
20470 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
20480 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
20490 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
204a0 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
204b0 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
204c0 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
204d0 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
204e0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
204f0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
20500 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
20510 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
20520 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
20530 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
20540 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
20550 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
20560 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
20570 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
20580 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
20590 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
205a0 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
205b0 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
205c0 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
205d0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
205e0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
205f0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
20600 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
20610 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
20620 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
20630 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
20640 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
20650 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
20660 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
20670 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
20680 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
20690 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
206a0 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
206b0 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
206c0 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
206d0 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
206e0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
206f0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
20700 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
20710 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
20720 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
20730 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20740 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
20750 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
20760 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
20770 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
20780 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
20790 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
207a0 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
207b0 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
207c0 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
207d0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
207e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
207f0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
20800 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
20810 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
20820 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
20830 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
20840 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
20850 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
20860 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
20870 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
20880 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
20890 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
208a0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
208b0 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
208c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
208d0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
208e0 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
208f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20900 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
20910 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
20920 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
20930 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
20940 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
20950 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
20960 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
20970 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
20980 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
20990 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
209a0 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
209b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
209c0 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
209d0 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
209e0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
209f0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
20a00 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
20a10 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
20a20 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
20a30 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
20a40 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
20a50 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
20a60 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
20a70 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
20a80 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
20a90 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
20aa0 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
20ab0 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
20ac0 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
20ad0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
20ae0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
20af0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
20b00 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
20b10 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
20b20 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
20b30 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
20b40 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
20b50 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
20b60 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
20b70 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
20b80 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
20b90 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
20ba0 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
20bb0 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
20bc0 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
20bd0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
20be0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
20bf0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
20c00 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
20c10 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
20c20 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
20c30 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
20c40 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
20c50 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
20c60 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
20c70 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
20c80 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
20c90 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
20ca0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
20cb0 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
20cc0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
20cd0 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
20ce0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
20cf0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
20d00 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
20d10 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
20d20 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
20d30 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
20d40 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
20d50 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
20d60 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
20d70 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
20d80 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
20d90 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
20da0 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
20db0 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
20dc0 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
20dd0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
20de0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
20df0 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
20e00 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
20e10 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
20e20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
20e30 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
20e40 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
20e50 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
20e60 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
20e70 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
20e80 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
20e90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
20ea0 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
20eb0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
20ec0 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
20ed0 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
20ee0 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
20ef0 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
20f00 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
20f10 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
20f20 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
20f30 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
20f40 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
20f50 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
20f60 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
20f70 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
20f80 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
20f90 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
20fa0 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
20fb0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
20fc0 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
20fd0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
20fe0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
20ff0 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
21000 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
21010 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
21020 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
21030 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
21040 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
21050 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
21060 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
21070 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
21080 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
21090 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
210a0 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
210b0 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
210c0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
210d0 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
210e0 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
210f0 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
21100 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
21110 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
21120 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
21130 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
21140 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
21150 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
21160 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
21170 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
21180 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
21190 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
211a0 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
211b0 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
211c0 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
211d0 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
211e0 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
211f0 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
21200 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
21210 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
21220 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
21230 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
21240 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
21250 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
21260 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
21270 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
21280 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
21290 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
212a0 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
212b0 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
212c0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
212d0 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
212e0 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
212f0 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
21300 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
21310 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
21320 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
21330 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
21340 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
21350 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
21360 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
21370 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
21380 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
21390 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
213a0 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
213b0 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
213c0 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
213d0 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
213e0 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
213f0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
21400 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
21410 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
21420 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e  ath. .** ^On win
21430 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
21440 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
21450 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
21460 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
21470 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
21480 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   "C:")..**.** [[
21490 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
214a0 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
214b0 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
214c0 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
214d0 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
214e0 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
214f0 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
21500 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
21510 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
21520 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
21530 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
21540 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72  * SQLite interpr
21550 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ets the followin
21560 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61  g three query pa
21570 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
21580 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
21590 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
215a0 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
215b0 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
215c0 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
215d0 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
215e0 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
215f0 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
21600 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
21610 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
21620 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
21630 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
21640 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
21650 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
21660 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
21670 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
21680 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
21690 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
216a0 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
216b0 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
216c0 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
216d0 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
216e0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
216f0 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
21700 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
21710 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
21720 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
21730 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
21740 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
21750 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
21760 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
21770 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
21780 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
21790 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
217a0 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
217b0 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
217c0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
217d0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
217e0 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
217f0 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
21800 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
21810 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
21820 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
21830 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
21840 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
21850 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
21860 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
21870 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
21880 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
21890 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
218a0 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
218b0 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
218c0 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
218d0 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
218e0 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
218f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
21900 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
21910 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
21920 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
21930 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
21940 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
21950 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
21960 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
21970 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
21980 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
21990 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
219a0 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
219b0 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
219c0 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
219d0 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
219e0 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
219f0 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
21a00 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
21a10 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
21a20 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20  E_OPEN_CREATE.  
21a30 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
21a40 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65  ion is.**     se
21a50 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68  t to "memory" th
21a60 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65  en a pure [in-me
21a70 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74  mory database] t
21a80 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a  hat never reads.
21a90 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73  **     or writes
21aa0 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73   from disk is us
21ab0 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72  ed. ^It is an er
21ac0 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
21ad0 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20   value for.**   
21ae0 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d    the mode param
21af0 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73  eter that is les
21b00 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
21b10 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
21b20 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20  d by.**     the 
21b30 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20  flags passed in 
21b40 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
21b50 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
21b60 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
21b70 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
21b80 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
21b90 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
21ba0 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
21bb0 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
21bc0 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
21bd0 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
21be0 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
21bf0 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
21c00 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
21c10 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
21c20 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
21c30 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
21c40 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
21c50 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
21c60 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
21c70 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
21c80 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
21c90 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
21ca0 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
21cb0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
21cc0 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
21cd0 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
21ce0 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
21cf0 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
21d00 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
21d10 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
21d20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
21d30 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
21d40 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72  des any behavior
21d50 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
21d60 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
21d70 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
21d80 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
21d90 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
21da0 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a   flag..** </ul>.
21db0 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e  **.** ^Specifyin
21dc0 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72  g an unknown par
21dd0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 20 71 75  ameter in the qu
21de0 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
21df0 20 61 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e   a URI is not an
21e00 0a 2a 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75  .** error.  Futu
21e10 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
21e20 51 4c 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65  QLite might unde
21e30 72 73 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61  rstand additiona
21e40 6c 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  l query.** param
21e50 65 74 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75  eters.  See "[qu
21e60 65 72 79 20 70 61 72 61 6d 65 74 65 72 73 20 77  ery parameters w
21e70 69 74 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e  ith special mean
21e80 69 6e 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20  ing to SQLite]" 
21e90 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61  for.** additiona
21ea0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
21eb0 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e  *.** [[URI filen
21ec0 61 6d 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c  ame examples]] <
21ed0 68 33 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  h3>URI filename 
21ee0 65 78 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a  examples</h3>.**
21ef0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
21f00 72 3d 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74  r="1" align=cent
21f10 65 72 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35  er cellpadding=5
21f20 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52  >.** <tr><th> UR
21f30 49 20 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e  I filenames <th>
21f40 20 52 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e   Results.** <tr>
21f50 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
21f60 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
21f70 20 20 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c      Open the fil
21f80 65 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74  e "data.db" in t
21f90 68 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63  he current direc
21fa0 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tory..** <tr><td
21fb0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
21fc0 64 2f 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a  d/data.db<br>.**
21fd0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
21fe0 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  //home/fred/data
21ff0 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20  .db <br> .**    
22000 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63        file://loc
22010 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64  alhost/home/fred
22020 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74  /data.db <br> <t
22030 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
22040 4f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  Open the databas
22050 65 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72  e file "/home/fr
22060 65 64 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20  ed/data.db"..** 
22070 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f  <tr><td> file://
22080 64 61 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72  darkstar/home/fr
22090 65 64 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  ed/data.db <td> 
220a0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20  .**          An 
220b0 65 72 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72  error. "darkstar
220c0 22 20 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67  " is not a recog
220d0 6e 69 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e  nized authority.
220e0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c  .** <tr><td styl
220f0 65 3d 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e  e="white-space:n
22100 6f 77 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20  owrap"> .**     
22110 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f       file:///C:/
22120 44 6f 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25  Documents%20and%
22130 32 30 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f  20Settings/fred/
22140 44 65 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a  Desktop/data.db.
22150 2a 2a 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64  **     <td> Wind
22160 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74  ows only: Open t
22170 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  he file "data.db
22180 22 20 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b  " on fred's desk
22190 74 6f 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20  top on drive.** 
221a0 20 20 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74           C:. Not
221b0 65 20 74 68 61 74 20 74 68 65 20 25 32 30 20 65  e that the %20 e
221c0 73 63 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20  scaping in this 
221d0 65 78 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73  example is not s
221e0 74 72 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20  trictly .**     
221f0 20 20 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d       necessary -
22200 20 73 70 61 63 65 20 63 68 61 72 61 63 74 65 72   space character
22210 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69  s can be used li
22220 74 65 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20  terally.**      
22230 20 20 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e      in URI filen
22240 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ames..** <tr><td
22250 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
22260 6f 64 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69  ode=ro&cache=pri
22270 76 61 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  vate <td> .**   
22280 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
22290 20 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68   "data.db" in th
222a0 65 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74  e current direct
222b0 6f 72 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c  ory for read-onl
222c0 79 20 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20  y access..**    
222d0 20 20 20 20 20 20 52 65 67 61 72 64 6c 65 73 73        Regardless
222e0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
222f0 6f 74 20 73 68 61 72 65 64 2d 63 61 63 68 65 20  ot shared-cache 
22300 6d 6f 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20  mode is enabled 
22310 62 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64  by.**          d
22320 65 66 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72  efault, use a pr
22330 69 76 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20  ivate cache..** 
22340 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
22350 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
22360 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b  ?vfs=unix-nolock
22370 20 3c 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20   <td>.**        
22380 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f    Open file "/ho
22390 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
223a0 2e 20 55 73 65 20 74 68 65 20 73 70 65 63 69 61  . Use the specia
223b0 6c 20 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f  l VFS "unix-nolo
223c0 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ck"..** <tr><td>
223d0 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f   file:data.db?mo
223e0 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e  de=readonly <td>
223f0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e   .**          An
22400 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c   error. "readonl
22410 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69  y" is not a vali
22420 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65  d option for the
22430 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65   "mode" paramete
22440 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  r..** </table>.*
22450 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65  *.** ^URI hexade
22460 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71  cimal escape seq
22470 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72 65  uences (%HH) are
22480 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68 69   supported withi
22490 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a  n the path and.*
224a0 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  * query componen
224b0 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68  ts of a URI. A h
224c0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
224d0 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69  e sequence consi
224e0 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63  sts of a.** perc
224f0 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d  ent sign - "%" -
22500 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61   followed by exa
22510 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63  ctly two hexadec
22520 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20  imal digits .** 
22530 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63  specifying an oc
22540 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f  tet value. ^Befo
22550 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20 71  re the path or q
22560 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20  uery components 
22570 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65  of a.** URI file
22580 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72  name are interpr
22590 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20 65  eted, they are e
225a0 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46  ncoded using UTF
225b0 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68  -8 and all .** h
225c0 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
225d0 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c  e sequences repl
225e0 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65  aced by a single
225f0 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67   byte containing
22600 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f   the.** correspo
22610 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20  nding octet. If 
22620 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e  this process gen
22630 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69  erates an invali
22640 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  d UTF-8 encoding
22650 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73  ,.** the results
22660 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
22670 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f  **.** <b>Note to
22680 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c   Windows users:<
22690 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e  /b>  The encodin
226a0 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20 66  g used for the f
226b0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
226c0 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  .** of sqlite3_o
226d0 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
226e0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74  3_open_v2() must
226f0 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77   be UTF-8, not w
22700 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70  hatever.** codep
22710 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79  age is currently
22720 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e   defined.  Filen
22730 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20  ames containing 
22740 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a  international.**
22750 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73 74   characters must
22760 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   be converted to
22770 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20   UTF-8 prior to 
22780 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74  passing them int
22790 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
227a0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f  n() or sqlite3_o
227b0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
227c0 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
227d0 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73  ws Runtime users
227e0 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f  :</b>  The tempo
227f0 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d  rary directory m
22800 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72  ust be set.** pr
22810 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73  ior to calling s
22820 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
22830 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
22840 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20  ().  Otherwise, 
22850 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75  various.** featu
22860 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72 65  res that require
22870 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70   the use of temp
22880 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20  orary files may 
22890 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  fail..**.** See 
228a0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74  also: [sqlite3_t
228b0 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a  emp_directory].*
228c0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
228d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20   sqlite3_open(. 
228e0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c   const char *fil
228f0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
22900 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
22910 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74  TF-8) */.  sqlit
22920 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20  e3 **ppDb       
22930 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74     /* OUT: SQLit
22940 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29  e db handle */.)
22950 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
22960 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
22970 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66  .  const void *f
22980 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61  ilename,   /* Da
22990 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
229a0 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71  (UTF-16) */.  sq
229b0 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
229c0 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
229d0 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
229e0 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
229f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
22a00 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
22a10 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
22a20 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
22a30 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
22a40 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
22a50 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
22a60 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
22a70 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
22a80 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
22a90 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
22aa0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
22ab0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
22ac0 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
22ad0 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
22ae0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
22af0 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
22b00 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
22b10 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
22b20 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
22b30 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
22b40 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
22b50 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
22b60 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
22b70 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
22b80 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
22b90 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
22ba0 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
22bb0 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
22bc0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
22bd0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
22be0 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
22bf0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
22c00 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
22c10 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
22c20 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
22c30 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
22c40 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
22c50 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
22c60 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
22c70 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
22c80 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
22c90 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
22ca0 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
22cb0 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
22cc0 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
22cd0 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
22ce0 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
22cf0 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
22d00 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
22d10 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
22d20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
22d30 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
22d40 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
22d50 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
22d60 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
22d70 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
22d80 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
22d90 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
22da0 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
22db0 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
22dc0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
22dd0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
22de0 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
22df0 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
22e00 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
22e10 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
22e20 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
22e30 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
22e40 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
22e50 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
22e60 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
22e70 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
22e80 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
22e90 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
22ea0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
22eb0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
22ec0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
22ed0 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
22ee0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
22ef0 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
22f00 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
22f10 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
22f20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
22f30 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
22f40 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
22f50 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
22f60 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
22f70 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
22f80 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
22f90 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
22fa0 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
22fb0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
22fc0 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
22fd0 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
22fe0 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
22ff0 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
23000 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
23010 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
23020 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
23030 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
23040 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
23050 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
23060 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
23070 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
23080 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
23090 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
230a0 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
230b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
230c0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
230d0 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
230e0 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
230f0 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
23100 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
23110 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
23120 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
23130 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
23140 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
23150 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
23160 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
23170 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
23180 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
23190 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
231a0 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
231b0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
231c0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
231d0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
231e0 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
231f0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
23200 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
23210 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
23220 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
23230 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
23240 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
23250 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
23260 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
23270 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
23280 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
23290 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
232a0 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
232b0 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
232c0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
232d0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
232e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
232f0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
23300 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
23310 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
23320 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
23330 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45  *zParam);.SQLITE
23340 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
23350 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e  _uri_boolean(con
23360 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20  st char *zFile, 
23370 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72  const char *zPar
23380 61 6d 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74  am, int bDefault
23390 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
233a0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
233b0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f  te3_uri_int64(co
233c0 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74  nst char*, const
233d0 20 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f   char*, sqlite3_
233e0 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  int64);.../*.** 
233f0 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20  CAPI3REF: Error 
23400 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67  Codes And Messag
23410 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
23420 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
23430 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
23440 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72  s the numeric [r
23450 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a  esult code] or.*
23460 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
23470 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  lt code] for the
23480 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69   most recent fai
23490 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50  led sqlite3_* AP
234a0 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69  I call.** associ
234b0 61 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74  ated with a [dat
234c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
234d0 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50  ]. If a prior AP
234e0 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a  I call failed.**
234f0 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65   but the most re
23500 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75  cent API call su
23510 63 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74  cceeded, the ret
23520 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a  urn value from.*
23530 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  * sqlite3_errcod
23540 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64  e() is undefined
23550 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
23560 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65  extended_errcode
23570 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
23580 69 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65  is the same exce
23590 70 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79  pt that it alway
235a0 73 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a  s returns the .*
235b0 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75  * [extended resu
235c0 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68  lt code] even wh
235d0 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  en extended resu
235e0 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20  lt codes are.** 
235f0 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  disabled..**.** 
23600 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
23610 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65  msg() and sqlite
23620 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74  3_errmsg16() ret
23630 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  urn English-lang
23640 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61  uage.** text tha
23650 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
23660 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72  error, as either
23670 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
23680 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
23690 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f  * ^(Memory to ho
236a0 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ld the error mes
236b0 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d  sage string is m
236c0 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c  anaged internall
236d0 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  y..** The applic
236e0 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e  ation does not n
236f0 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f  eed to worry abo
23700 75 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72  ut freeing the r
23710 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65  esult..** Howeve
23720 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72  r, the error str
23730 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65  ing might be ove
23740 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c  rwritten or deal
23750 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75  located by.** su
23760 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
23770 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69  o other SQLite i
23780 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f  nterface functio
23790 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ns.)^.**.** ^The
237a0 20 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28   sqlite3_errstr(
237b0 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
237c0 72 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d  rns the English-
237d0 6c 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a  language text.**
237e0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
237f0 74 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  the [result code
23800 5d 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20  ], as UTF-8..** 
23810 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
23820 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
23830 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
23840 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  aged internally.
23850 2a 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20  ** and must not 
23860 62 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20  be freed by the 
23870 61 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a  application)^..*
23880 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
23890 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
238a0 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
238b0 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
238c0 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
238d0 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
238e0 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
238f0 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
23900 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
23910 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
23920 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
23930 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
23940 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
23950 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
23960 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
23970 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
23980 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
23990 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
239a0 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
239b0 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
239c0 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
239d0 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
239e0 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
239f0 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
23a00 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
23a10 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
23a20 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
23a30 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
23a40 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
23a50 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
23a60 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
23a70 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
23a80 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
23a90 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
23aa0 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
23ab0 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
23ac0 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
23ad0 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
23ae0 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
23af0 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
23b00 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
23b10 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
23b20 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
23b30 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
23b40 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
23b50 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
23b60 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
23b70 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
23b80 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
23b90 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
23ba0 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  e set..*/.SQLITE
23bb0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
23bc0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
23bd0 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
23be0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  I int sqlite3_ex
23bf0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
23c00 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c  qlite3 *db);.SQL
23c10 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
23c20 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
23c30 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  sg(sqlite3*);.SQ
23c40 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
23c50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
23c60 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
23c70 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
23c80 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
23c90 65 72 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a  errstr(int);../*
23ca0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
23cb0 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
23cc0 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
23cd0 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
23ce0 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
23cf0 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
23d00 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
23d10 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
23d20 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
23d30 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
23d40 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
23d50 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
23d60 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
23d70 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
23d80 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
23d90 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
23da0 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
23db0 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
23dc0 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
23dd0 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
23de0 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
23df0 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
23e00 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
23e10 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
23e20 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
23e30 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
23e40 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
23e50 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
23e60 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
23e70 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
23e80 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
23e90 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
23ea0 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
23eb0 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
23ec0 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
23ed0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23ee0 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
23ef0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
23f00 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
23f10 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
23f20 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
23f30 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
23f40 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
23f50 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
23f60 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
23f70 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
23f80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
23f90 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
23fa0 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
23fb0 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
23fc0 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
23fd0 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
23fe0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
23ff0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
24000 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
24010 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
24020 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
24030 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
24040 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
24050 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
24060 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
24070 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
24080 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
24090 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
240a0 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
240b0 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
240c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
240d0 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
240e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
240f0 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
24100 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
24110 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
24120 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
24130 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
24140 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
24150 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
24160 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
24170 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
24180 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
24190 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
241a0 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
241b0 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
241c0 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
241d0 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
241e0 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
241f0 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
24200 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
24210 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
24220 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
24230 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
24240 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
24250 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
24260 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
24270 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
24280 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
24290 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
242a0 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
242b0 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
242c0 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
242d0 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
242e0 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
242f0 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
24300 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
24310 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
24320 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
24330 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
24340 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
24350 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
24360 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
24370 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
24380 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
24390 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
243a0 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
243b0 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
243c0 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
243d0 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
243e0 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
243f0 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
24400 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
24410 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
24420 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
24430 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
24440 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
24450 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
24460 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
24470 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
24480 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
24490 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
244a0 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
244b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
244c0 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
244d0 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
244e0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
244f0 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
24500 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
24510 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
24520 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
24530 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
24540 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
24550 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
24560 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
24570 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
24580 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
24590 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
245a0 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
245b0 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
245c0 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
245d0 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
245e0 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
245f0 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
24600 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
24610 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
24620 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
24630 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
24640 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
24650 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
24660 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
24670 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
24680 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
24690 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
246a0 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
246b0 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
246c0 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
246d0 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
246e0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
246f0 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
24700 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
24710 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
24720 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
24730 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
24740 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
24750 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
24760 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
24770 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
24780 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
24790 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
247a0 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
247b0 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
247c0 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
247d0 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
247e0 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  es..*/.SQLITE_AP
247f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  I int sqlite3_li
24800 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
24810 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
24820 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
24830 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
24840 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
24850 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
24860 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
24870 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
24880 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
24890 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
248a0 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
248b0 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
248c0 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
248d0 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
248e0 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
248f0 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
24900 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
24910 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
24920 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
24930 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
24940 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
24950 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
24960 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
24970 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
24980 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
24990 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
249a0 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
249b0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
249c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
249d0 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
249e0 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
249f0 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
24a00 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
24a10 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
24a20 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
24a30 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
24a40 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
24a50 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
24a60 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
24a70 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
24a80 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
24a90 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
24aa0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
24ab0 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
24ac0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
24ad0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
24ae0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
24af0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
24b00 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
24b10 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
24b20 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
24b30 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
24b40 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
24b50 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
24b60 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
24b70 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
24b80 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
24b90 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
24ba0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
24bb0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
24bc0 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
24bd0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
24be0 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
24bf0 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
24c00 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
24c10 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
24c20 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
24c30 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
24c40 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
24c50 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
24c60 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
24c70 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
24c80 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
24c90 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
24ca0 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
24cb0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
24cc0 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
24cd0 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
24ce0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
24cf0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
24d00 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
24d10 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
24d20 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
24d30 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
24d40 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
24d50 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
24d60 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73  .  This limit is
24d70 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a   not currently.*
24d80 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75  * enforced, thou
24d90 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  gh that might be
24da0 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66   added in some f
24db0 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
24dc0 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  .** SQLite.</dd>
24dd0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
24de0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
24df0 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  _ARG]] ^(<dt>SQL
24e00 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
24e10 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
24e20 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
24e30 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
24e40 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
24e50 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
24e60 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  [SQLITE_LIMIT_AT
24e70 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53  TACHED]] ^(<dt>S
24e80 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
24e90 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
24ea0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
24eb0 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
24ec0 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
24ed0 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
24ee0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
24ef0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
24f00 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  ENGTH]].** ^(<dt
24f10 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
24f20 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
24f30 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
24f40 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
24f50 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
24f60 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
24f70 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
24f80 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
24f90 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
24fa0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
24fb0 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20  BLE_NUMBER]].** 
24fc0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
24fd0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
24fe0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
24ff0 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
25000 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
25010 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
25020 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
25030 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25040 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
25050 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
25060 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
25070 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
25080 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
25090 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
250a0 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
250b0 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
250c0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
250d0 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
250e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
250f0 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
25100 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
25110 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
25120 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
25130 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
25140 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
25150 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
25160 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
25170 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
25180 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
25190 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
251a0 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
251b0 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
251c0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
251d0 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
251e0 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
251f0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
25200 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
25210 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
25220 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25230 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
25240 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
25250 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25260 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
25270 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
25280 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25290 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
252a0 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
252b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
252c0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
252d0 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a              10..
252e0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
252f0 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
25300 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
25310 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
25320 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
25330 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
25340 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
25350 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
25360 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
25370 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
25380 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
25390 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
253a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
253b0 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
253c0 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
253d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
253e0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
253f0 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
25400 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
25410 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
25420 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
25430 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
25440 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
25450 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
25460 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
25470 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
25480 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
25490 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
254a0 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
254b0 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
254c0 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
254d0 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
254e0 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
254f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
25500 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
25510 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
25520 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
25530 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
25540 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
25550 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
25560 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
25570 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
25580 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
25590 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
255a0 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
255b0 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
255c0 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
255d0 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
255e0 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
255f0 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
25600 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
25610 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
25620 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
25630 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e  ^When nByte is n
25640 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
25650 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
25660 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
25670 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
25680 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
25690 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
256a0 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
256b0 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
256c0 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
256d0 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
256e0 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
256f0 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
25700 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
25710 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
25720 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
25730 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
25740 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
25750 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
25760 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
25770 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
25780 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
25790 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
257a0 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
257b0 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
257c0 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74  nator bytes as t
257d0 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65  his saves SQLite
257e0 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a   from having to.
257f0 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f  ** make a copy o
25800 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
25810 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  ng..**.** ^If pz
25820 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
25830 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
25840 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
25850 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
25860 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
25870 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
25880 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
25890 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
258a0 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
258b0 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
258c0 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
258d0 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
258e0 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
258f0 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
25900 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
25910 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
25920 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
25930 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
25940 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
25950 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
25960 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
25970 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
25980 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
25990 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
259a0 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
259b0 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
259c0 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
259d0 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
259e0 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
259f0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
25a00 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
25a10 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
25a20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
25a30 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
25a40 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
25a50 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
25a60 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
25a70 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
25a80 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
25a90 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
25aa0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
25ab0 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
25ac0 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
25ad0 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
25ae0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
25af0 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
25b00 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
25b10 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
25b20 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
25b30 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
25b40 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
25b50 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
25b60 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
25b70 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
25b80 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
25b90 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
25ba0 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
25bb0 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
25bc0 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
25bd0 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
25be0 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
25bf0 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
25c00 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
25c10 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
25c20 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
25c30 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
25c40 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
25c50 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
25c60 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
25c70 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
25c80 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
25c90 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
25ca0 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
25cb0 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
25cc0 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
25cd0 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
25ce0 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
25cf0 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
25d00 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
25d10 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
25d20 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
25d30 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
25d40 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
25d50 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
25d60 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
25d70 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
25d80 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
25d90 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
25da0 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
25db0 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
25dc0 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
25dd0 20 41 73 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c   As many as [SQL
25de0 49 54 45 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52  ITE_MAX_SCHEMA_R
25df0 45 54 52 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73  ETRY].** retries
25e00 20 77 69 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f   will occur befo
25e10 72 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  re sqlite3_step(
25e20 29 20 67 69 76 65 73 20 75 70 20 61 6e 64 20 72  ) gives up and r
25e30 65 74 75 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e  eturns an error.
25e40 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
25e50 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
25e60 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
25e70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
25e80 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
25e90 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
25ea0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
25eb0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
25ec0 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
25ed0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
25ee0 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
25ef0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
25f00 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
25f10 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
25f20 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
25f30 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
25f40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
25f50 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
25f60 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
25f70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
25f80 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
25f90 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
25fa0 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
25fb0 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
25fc0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
25fd0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
25fe0 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
25ff0 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
26000 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
26010 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
26020 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
26030 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
26040 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
26050 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
26060 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
26070 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
26080 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
26090 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
260a0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
260b0 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
260c0 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
260d0 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
260e0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
260f0 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
26100 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
26110 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
26120 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
26130 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
26140 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
26150 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
26160 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
26170 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
26180 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
26190 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
261a0 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
261b0 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
261c0 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
261d0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
261e0 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
261f0 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
26200 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
26210 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
26220 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
26230 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
26240 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
26250 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
26260 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
26270 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
26280 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
26290 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
262a0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
262b0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
262c0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a  </li>.** </ol>.*
262d0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
262e0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
262f0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
26300 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
26310 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
26320 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
26330 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
26340 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
26350 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20  F-8 encoded */. 
26360 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20   int nByte,     
26370 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
26380 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53  mum length of zS
26390 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a  ql in bytes. */.
263a0 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a    sqlite3_stmt *
263b0 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54  *ppStmt,  /* OUT
263c0 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  : Statement hand
263d0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
263e0 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20  ar **pzTail     
263f0 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20  /* OUT: Pointer 
26400 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f  to unused portio
26410 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a  n of zSql */.);.
26420 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
26430 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
26440 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
26450 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
26460 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
26470 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
26480 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
26490 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
264a0 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
264b0 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
264c0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
264d0 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
264e0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
264f0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
26500 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
26510 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
26520 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
26530 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
26540 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
26550 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
26560 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
26570 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
26580 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
26590 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
265a0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
265b0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
265c0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
265d0 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
265e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
265f0 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
26600 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
26610 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
26620 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
26630 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
26640 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
26650 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
26660 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
26670 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
26680 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
26690 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
266a0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
266b0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
266c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
266d0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
266e0 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  16_v2(.  sqlite3
266f0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
26700 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
26710 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
26720 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  oid *zSql,      
26730 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
26740 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  t, UTF-16 encode
26750 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
26760 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
26770 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
26780 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
26790 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
267a0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
267b0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
267c0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
267d0 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69  nst void **pzTai
267e0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
267f0 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
26800 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
26810 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
26820 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e  I3REF: Retrievin
26830 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a  g Statement SQL.
26840 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
26850 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
26860 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61 20  d to retrieve a 
26870 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68  saved copy of th
26880 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51  e original.** SQ
26890 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20 63  L text used to c
268a0 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72 65  reate a [prepare
268b0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20  d statement] if 
268c0 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77  that statement w
268d0 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75  as.** compiled u
268e0 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c  sing either [sql
268f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26900 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
26910 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
26920 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
26930 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
26940 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
26950 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
26960 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
26970 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
26980 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65   Statement Write
26990 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a  s The Database.*
269a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
269b0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
269c0 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
269d0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
269e0 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
269f0 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
26a00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
26a10 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
26a20 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
26a30 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
26a40 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
26a50 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
26a60 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
26a70 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
26a80 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
26a90 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
26aa0 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
26ab0 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
26ac0 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
26ad0 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
26ae0 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
26af0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
26b00 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
26b10 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
26b20 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
26b30 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
26b40 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
26b50 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
26b60 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
26b70 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
26b80 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
26b90 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
26ba0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
26bb0 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
26bc0 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
26bd0 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
26be0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
26bf0 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
26c00 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
26c10 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
26c20 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
26c30 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
26c40 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
26c50 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
26c60 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
26c70 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
26c80 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
26c90 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
26ca0 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
26cb0 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
26cc0 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
26cd0 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
26ce0 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
26cf0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
26d00 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
26d10 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
26d20 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
26d30 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
26d40 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
26d50 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
26d60 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
26d70 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
26d80 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
26d90 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
26da0 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
26db0 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
26dc0 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
26dd0 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
26de0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
26df0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
26e00 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
26e10 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
26e20 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
26e30 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
26e40 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
26e50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
26e60 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
26e70 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
26e80 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
26e90 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
26ea0 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c   on disk..*/.SQL
26eb0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
26ec0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
26ed0 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  y(sqlite3_stmt *
26ee0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
26ef0 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
26f00 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65 64  ne If A Prepared
26f10 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20 42   Statement Has B
26f20 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20  een Reset.**.** 
26f30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
26f40 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72 66  t_busy(S) interf
26f50 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
26f60 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20 74   (non-zero) if t
26f70 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
26f80 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61 73  statement] S has
26f90 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61 74   been stepped at
26fa0 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69 6e   least once usin
26fb0 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  g .** [sqlite3_s
26fc0 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73 20  tep(S)] but has 
26fd0 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70 6c  not run to compl
26fe0 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61 73  etion and/or has
26ff0 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72 65   not .** been re
27000 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  set using [sqlit
27010 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20 5e  e3_reset(S)].  ^
27020 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  The sqlite3_stmt
27030 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74 65  _busy(S).** inte
27040 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66 61  rface returns fa
27050 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e 55  lse if S is a NU
27060 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66 20  LL pointer.  If 
27070 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e  S is not a .** N
27080 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  ULL pointer and 
27090 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65 72  is not a pointer
270a0 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72 65   to a valid [pre
270b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
270c0 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65 6e  .** object, then
270d0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
270e0 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70   undefined and p
270f0 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72 61  robably undesira
27100 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ble..**.** This 
27110 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
27120 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e 61   used in combina
27130 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e 65  tion [sqlite3_ne
27140 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f  xt_stmt()].** to
27150 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65 70   locate all prep
27160 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 20  ared statements 
27170 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20  associated with 
27180 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20 63  a database .** c
27190 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 61  onnection that a
271a0 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62 65  re in need of be
271b0 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69 73  ing reset.  This
271c0 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a 2a   can be used,.**
271d0 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 6e   for example, in
271e0 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75 74   diagnostic rout
271f0 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20 66  ines to search f
27200 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a 20  or prepared .** 
27210 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20  statements that 
27220 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74 72  are holding a tr
27230 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a  ansaction open..
27240 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
27250 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  t sqlite3_stmt_b
27260 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  usy(sqlite3_stmt
27270 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
27280 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
27290 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
272a0 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
272b0 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
272c0 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
272d0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
272e0 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
272f0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
27300 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
27310 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
27320 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
27330 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
27340 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
27350 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
27360 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
27370 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
27380 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
27390 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
273a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
273b0 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
273c0 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
273d0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
273e0 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
273f0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
27400 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
27410 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
27420 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
27430 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
27440 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
27450 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
27460 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
27470 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
27480 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
27490 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
274a0 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
274b0 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
274c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
274d0 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
274e0 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
274f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
27500 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
27510 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
27520 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
27530 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
27540 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
27550 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
27560 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
27570 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
27580 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
27590 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
275a0 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c  ld.  An internal
275b0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
275c0 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
275d0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
275e0 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
275f0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
27600 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
27610 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
27620 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
27630 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
27640 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
27650 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
27660 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
27670 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
27680 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
27690 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
276a0 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
276b0 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
276c0 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
276d0 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
276e0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
276f0 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
27700 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
27710 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
27720 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
27730 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
27740 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
27750 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
27760 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
27770 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
27780 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
27790 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
277a0 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
277b0 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
277c0 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
277d0 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
277e0 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
277f0 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
27800 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
27810 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
27820 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
27830 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
27840 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
27850 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
27860 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
27870 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
27880 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
27890 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
278a0 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
278b0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
278c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
278d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
278e0 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
278f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
27900 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
27910 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
27920 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
27930 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
27940 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
27950 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27960 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
27970 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
27980 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
27990 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
279a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
279b0 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  ue()]..** The [s
279c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
279d0 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
279e0 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
279f0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
27a00 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
27a10 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27a20 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
27a30 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
27a40 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
27a50 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27a60 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
27a70 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
27a80 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
27a90 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
27aa0 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
27ab0 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
27ac0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
27ad0 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
27ae0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
27af0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
27b00 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
27b10 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
27b20 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
27b30 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
27b40 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
27b50 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
27b60 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
27b70 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
27b80 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
27b90 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
27ba0 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
27bb0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
27bc0 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
27bd0 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
27be0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
27bf0 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
27c00 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
27c10 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
27c20 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
27c30 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
27c40 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
27c50 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
27c60 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
27c70 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
27c80 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
27c90 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
27ca0 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
27cb0 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
27cc0 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
27cd0 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
27ce0 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
27cf0 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
27d00 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
27d10 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
27d20 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
27d30 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
27d40 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
27d50 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
27d60 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  g}.**.** ^(In th
27d70 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
27d80 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
27d90 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
27da0 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
27db0 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
27dc0 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
27dd0 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
27de0 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
27df0 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
27e00 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
27e10 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
27e20 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
27e30 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
27e40 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
27e50 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
27e60 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
27e70 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
27e80 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
27e90 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
27ea0 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
27eb0 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
27ec0 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
27ed0 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
27ee0 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
27ef0 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
27f00 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
27f10 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
27f20 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
27f30 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
27f40 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
27f50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
27f60 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
27f70 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
27f80 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
27f90 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
27fa0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
27fb0 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
27fc0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
27fd0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
27fe0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
27ff0 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
28000 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
28010 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
28020 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
28030 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
28040 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
28050 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
28060 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
28070 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
28080 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
28090 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
280a0 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
280b0 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
280c0 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
280d0 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
280e0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
280f0 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
28100 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
28110 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
28120 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
28130 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
28140 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
28150 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
28160 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
28170 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28180 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
28190 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
281a0 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
281b0 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
281c0 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
281d0 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
281e0 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
281f0 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
28200 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
28210 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
28220 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
28230 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
28240 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
28250 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
28260 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
28270 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
28280 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
28290 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
282a0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
282b0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
282c0 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
282d0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
282e0 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  6().** or sqlite
282f0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
28300 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
28310 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
28320 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
28330 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20  ignored and the 
28340 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68  end result is th
28350 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65  e same as sqlite
28360 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a  3_bind_null()..*
28370 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
28380 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
28390 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
283a0 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
283b0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
283c0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
283d0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
283e0 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
283f0 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
28400 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
28410 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
28420 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
28430 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
28440 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
28450 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
28460 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
28470 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
28480 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
28490 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
284a0 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  hen the length o
284b0 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
284c0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
284d0 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
284e0 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
284f0 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68  inator..** If th
28500 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
28510 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
28520 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67  nd_blob() is neg
28530 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74  ative, then.** t
28540 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
28550 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
28560 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
28570 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
28580 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
28590 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
285a0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
285b0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74  _bind_text16() t
285c0 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74  hen that paramet
285d0 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
285e0 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
285f0 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
28600 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
28610 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
28620 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
28630 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
28640 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
28650 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
28660 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
28670 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
28680 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
28690 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
286a0 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
286b0 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
286c0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
286d0 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
286e0 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
286f0 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
28700 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
28710 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
28720 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
28730 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
28740 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
28750 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
28760 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
28770 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
28780 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
28790 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
287a0 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
287b0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
287c0 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
287d0 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
287e0 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
287f0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
28800 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
28810 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
28820 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
28830 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73  if the call to s
28840 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
28850 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  (),.** sqlite3_b
28860 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73  ind_text(), or s
28870 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28880 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a  16() fails.  .**
28890 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
288a0 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
288b0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
288c0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
288d0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
288e0 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
288f0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
28900 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
28910 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
28920 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
28930 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
28940 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
28950 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
28960 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
28970 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
28980 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
28990 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
289a0 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
289b0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
289c0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
289d0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
289e0 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
289f0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
28a00 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
28a10 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
28a20 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
28a30 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
28a40 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
28a50 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
28a60 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
28a70 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
28a80 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
28a90 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
28aa0 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
28ab0 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
28ac0 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
28ad0 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
28ae0 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
28af0 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
28b00 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
28b10 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
28b20 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
28b30 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
28b40 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
28b50 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
28b60 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
28b70 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
28b80 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
28b90 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
28ba0 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
28bb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
28bc0 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
28bd0 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
28be0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
28bf0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
28c00 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
28c10 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
28c20 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
28c30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
28c40 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
28c50 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
28c60 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
28c70 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
28c80 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
28c90 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
28ca0 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
28cb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
28cc0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
28cd0 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
28ce0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
28cf0 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
28d00 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
28d10 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
28d20 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
28d30 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
28d40 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
28d50 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
28d60 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
28d70 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
28d80 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
28d90 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
28da0 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
28db0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
28dc0 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
28dd0 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
28de0 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
28df0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
28e00 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
28e10 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
28e20 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
28e30 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
28e40 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
28e50 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
28e60 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
28e70 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
28e80 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
28e90 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
28ea0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
28eb0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
28ec0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
28ed0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
28ee0 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
28ef0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
28f00 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
28f10 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
28f20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
28f30 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
28f40 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
28f50 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
28f60 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
28f70 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
28f80 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
28f90 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
28fa0 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54  , double);.SQLIT
28fb0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
28fc0 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
28fd0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
28fe0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
28ff0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29000 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
29010 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
29020 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  e3_int64);.SQLIT
29030 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
29040 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
29050 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
29060 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29070 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
29080 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
29090 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
290a0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
290b0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
290c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
290d0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
290e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
290f0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
29100 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
29110 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
29120 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29130 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
29140 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
29150 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
29160 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
29170 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
29180 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
29190 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
291a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
291b0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
291c0 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  L Parameters.**.
291d0 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
291e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
291f0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
29200 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
29210 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
29220 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29230 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
29240 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
29250 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
29260 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
29270 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
29280 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
29290 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
292a0 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
292b0 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
292c0 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
292d0 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
292e0 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
292f0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
29300 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
29310 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
29320 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
29330 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
29340 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
29350 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
29360 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
29370 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
29380 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
29390 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
293a0 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
293b0 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
293c0 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
293d0 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
293e0 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
293f0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
29400 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
29410 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
29420 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
29430 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29440 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
29450 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
29460 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
29470 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
29480 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
29490 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
294a0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
294b0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
294c0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
294d0 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
294e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
294f0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29500 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
29510 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
29520 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
29530 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
29540 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
29550 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29560 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
29570 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
29580 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
29590 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
295a0 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
295b0 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
295c0 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
295d0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
295e0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
295f0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
29600 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
29610 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
29620 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
29630 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
29640 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
29650 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
29660 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
29670 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
29680 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
29690 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
296a0 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
296b0 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
296c0 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
296d0 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
296e0 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
296f0 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
29700 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
29710 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
29720 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
29730 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
29740 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
29750 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
29760 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
29770 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
29780 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
29790 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
297a0 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
297b0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
297c0 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
297d0 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
297e0 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
297f0 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
29800 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
29810 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
29820 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
29830 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
29840 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
29850 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
29860 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
29870 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
29880 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
29890 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
298a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
298b0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
298c0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
298d0 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
298e0 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
298f0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29900 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
29910 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
29920 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
29930 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a  A Given Name.**.
29940 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
29950 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
29960 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
29970 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
29980 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
29990 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
299a0 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
299b0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
299c0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
299d0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
299e0 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
299f0 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
29a00 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
29a10 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
29a20 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
29a30 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
29a40 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
29a50 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
29a60 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
29a70 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
29a80 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
29a90 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
29aa0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
29ab0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
29ac0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
29ad0 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
29ae0 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
29af0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29b00 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
29b10 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
29b20 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
29b30 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
29b40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
29b50 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
29b60 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
29b70 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
29b80 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
29b90 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
29ba0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
29bb0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
29bc0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  tement.**.** ^Co
29bd0 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
29be0 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
29bf0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
29c00 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
29c10 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
29c20 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
29c30 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
29c40 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29c50 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
29c60 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
29c70 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
29c80 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
29c90 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29ca0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
29cb0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
29cc0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
29cd0 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
29ce0 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
29cf0 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
29d00 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
29d10 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
29d20 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
29d30 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
29d40 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
29d50 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
29d60 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
29d70 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
29d80 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
29d90 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
29da0 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
29db0 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
29dc0 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  TE])..**.** See 
29dd0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
29de0 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
29df0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
29e00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
29e10 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
29e20 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
29e30 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
29e40 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
29e50 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult Set.**.** ^T
29e60 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
29e70 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
29e80 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
29e90 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
29ea0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
29eb0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
29ec0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
29ed0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
29ee0 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
29ef0 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
29f00 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
29f10 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
29f20 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
29f30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
29f40 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
29f50 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
29f60 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
29f70 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
29f80 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
29f90 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
29fa0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29fb0 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
29fc0 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
29fd0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
29fe0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
29ff0 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
2a000 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
2a010 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2a020 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
2a030 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
2a040 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
2a050 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
2a060 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
2a070 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2a080 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
2a090 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
2a0a0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
2a0b0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
2a0c0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
2a0d0 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
2a0e0 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
2a0f0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2a100 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
2a110 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
2a120 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
2a130 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2a140 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2a150 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2a160 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
2a170 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
2a180 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
2a190 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
2a1a0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
2a1b0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
2a1c0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
2a1d0 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
2a1e0 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
2a1f0 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
2a200 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
2a210 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2a220 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2a230 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
2a240 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
2a250 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
2a260 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
2a270 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
2a280 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
2a290 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
2a2a0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
2a2b0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
2a2c0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
2a2d0 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
2a2e0 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
2a2f0 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
2a300 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
2a310 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c  the next..*/.SQL
2a320 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2a330 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2a340 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
2a350 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53  stmt*, int N);.S
2a360 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2a370 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2a380 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
2a390 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2a3a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a3b0 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
2a3c0 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
2a3d0 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  sult.**.** ^Thes
2a3e0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
2a3f0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
2a400 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
2a410 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2a420 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
2a430 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
2a440 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
2a450 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
2a460 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
2a470 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
2a480 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2a490 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
2a4a0 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
2a4b0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
2a4c0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
2a4d0 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2a4e0 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
2a4f0 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
2a500 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
2a510 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
2a520 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
2a530 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
2a540 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
2a550 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
2a560 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
2a570 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
2a580 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2a590 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
2a5a0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2a5b0 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
2a5c0 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
2a5d0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2a5e0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2a5f0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2a600 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2a610 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2a620 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2a630 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2a640 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2a650 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2a660 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
2a670 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
2a680 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
2a690 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
2a6a0 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
2a6b0 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
2a6c0 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
2a6d0 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
2a6e0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
2a6f0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2a700 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2a710 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2a720 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
2a730 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
2a740 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a750 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
2a760 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
2a770 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
2a780 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
2a790 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2a7a0 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
2a7b0 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
2a7c0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
2a7d0 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
2a7e0 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
2a7f0 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
2a800 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
2a810 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
2a820 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
2a830 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
2a840 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
2a850 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
2a860 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
2a870 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
2a880 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
2a890 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2a8a0 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
2a8b0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
2a8c0 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
2a8d0 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
2a8e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2a8f0 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
2a900 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
2a910 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2a920 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
2a930 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2a940 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
2a950 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
2a960 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
2a970 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
2a980 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
2a990 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
2a9a0 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
2a9b0 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
2a9c0 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
2a9d0 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
2a9e0 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
2a9f0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2aa00 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
2aa10 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
2aa20 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2aa30 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2aa40 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2aa50 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2aa60 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2aa70 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2aa80 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
2aa90 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2aaa0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2aab0 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
2aac0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
2aad0 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
2aae0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2aaf0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
2ab00 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2ab10 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2ab20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
2ab30 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2ab40 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2ab50 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
2ab60 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2ab70 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2ab80 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
2ab90 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
2aba0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
2abb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2abc0 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
2abd0 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
2abe0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2abf0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2ac00 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c  ndefined..*/.SQL
2ac10 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2ac20 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2ac30 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2ac40 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2ac50 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2ac60 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2ac70 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2ac80 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
2ac90 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2aca0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2acb0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2acc0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
2acd0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2ace0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2acf0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2ad00 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2ad10 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2ad20 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2ad30 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2ad40 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2ad50 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
2ad60 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2ad70 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2ad80 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2ad90 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2ada0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2adb0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2adc0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
2add0 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
2ade0 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2adf0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
2ae00 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
2ae10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ae20 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
2ae30 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
2ae40 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2ae50 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
2ae60 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
2ae70 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
2ae80 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
2ae90 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
2aea0 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
2aeb0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2aec0 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
2aed0 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
2aee0 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
2aef0 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
2af00 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
2af10 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
2af20 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
2af30 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
2af40 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
2af50 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
2af60 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2af70 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2af80 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
2af90 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
2afa0 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
2afb0 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
2afc0 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
2afd0 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
2afe0 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
2aff0 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
2b000 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
2b010 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
2b020 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
2b030 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
2b040 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
2b050 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
2b060 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
2b070 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
2b080 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
2b090 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
2b0a0 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
2b0b0 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
2b0c0 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
2b0d0 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
2b0e0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
2b0f0 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
2b100 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
2b110 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
2b120 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
2b130 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
2b140 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
2b150 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
2b160 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
2b170 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
2b180 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
2b190 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
2b1a0 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
2b1b0 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
2b1c0 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
2b1d0 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
2b1e0 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
2b1f0 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
2b200 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
2b210 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
2b220 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
2b230 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
2b240 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lues..*/.SQLITE_
2b250 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2b260 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2b270 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
2b280 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2b290 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2b2a0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2b2b0 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
2b2c0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2b2d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b2e0 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
2b2f0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  L Statement.**.*
2b300 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
2b310 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
2b320 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
2b330 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
2b340 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b350 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2b360 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2b370 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
2b380 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2b390 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
2b3a0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
2b3b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2b3c0 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
2b3d0 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
2b3e0 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
2b3f0 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
2b400 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
2b410 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
2b420 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
2b430 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
2b440 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
2b450 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
2b460 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
2b470 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
2b480 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
2b490 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
2b4a0 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
2b4b0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2b4c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2b4d0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
2b4e0 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
2b4f0 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
2b500 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2b510 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2b520 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
2b530 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
2b540 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2b550 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
2b560 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
2b570 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
2b580 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2b590 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
2b5a0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
2b5b0 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
2b5c0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
2b5d0 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2b5e0 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
2b5f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
2b600 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
2b610 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
2b620 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
2b630 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2b640 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
2b650 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
2b660 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
2b670 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
2b680 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
2b690 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
2b6a0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
2b6b0 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
2b6c0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
2b6d0 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
2b6e0 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
2b6f0 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
2b700 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
2b710 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
2b720 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
2b730 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
2b740 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
2b750 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
2b760 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
2b770 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2b780 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
2b790 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
2b7a0 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
2b7b0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
2b7c0 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
2b7d0 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
2b7e0 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
2b7f0 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
2b800 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
2b810 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2b820 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
2b830 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
2b840 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
2b850 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
2b860 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
2b870 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
2b880 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
2b890 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2b8a0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2b8b0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
2b8c0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2b8d0 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
2b8e0 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2b8f0 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
2b900 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
2b910 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
2b920 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
2b930 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
2b940 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2b950 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
2b960 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
2b970 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
2b980 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
2b990 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
2b9a0 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
2b9b0 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
2b9c0 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
2b9d0 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
2b9e0 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
2b9f0 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
2ba00 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2ba10 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
2ba20 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
2ba30 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
2ba40 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
2ba50 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
2ba60 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
2ba70 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
2ba80 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
2ba90 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
2baa0 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
2bab0 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
2bac0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2bad0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2bae0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
2baf0 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
2bb00 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
2bb10 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
2bb20 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
2bb30 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
2bb40 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2bb50 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
2bb60 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2bb70 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
2bb80 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
2bb90 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
2bba0 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
2bbb0 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
2bbc0 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
2bbd0 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
2bbe0 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2bbf0 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
2bc00 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2bc10 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
2bc20 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2bc30 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
2bc40 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2bc50 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
2bc60 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
2bc70 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
2bc80 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
2bc90 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
2bca0 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
2bcb0 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
2bcc0 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
2bcd0 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
2bce0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2bcf0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2bd00 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
2bd10 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
2bd20 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
2bd30 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
2bd40 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
2bd50 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
2bd60 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
2bd70 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
2bd80 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
2bd90 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
2bda0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2bdb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
2bdc0 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
2bdd0 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
2bde0 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
2bdf0 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
2be00 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
2be10 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2be20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
2be30 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
2be40 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2be50 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
2be60 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
2be70 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
2be80 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
2be90 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
2bea0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
2beb0 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
2bec0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
2bed0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2bee0 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
2bef0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2bf00 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
2bf10 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
2bf20 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
2bf30 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
2bf40 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
2bf50 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
2bf60 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
2bf70 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
2bf80 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
2bf90 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
2bfa0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2bfb0 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
2bfc0 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
2bfd0 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
2bfe0 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
2bff0 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
2c000 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
2c010 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
2c020 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
2c030 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
2c040 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
2c050 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
2c060 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
2c070 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
2c080 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
2c090 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
2c0a0 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
2c0b0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2c0c0 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
2c0d0 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
2c0e0 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
2c0f0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
2c100 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
2c110 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
2c120 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2c130 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
2c140 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
2c150 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
2c160 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
2c170 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2c180 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
2c190 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
2c1a0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
2c1b0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
2c1c0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
2c1d0 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
2c1e0 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2c1f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2c200 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
2c210 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
2c220 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2c230 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
2c240 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
2c250 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
2c260 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
2c270 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
2c280 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
2c290 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
2c2a0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
2c2b0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
2c2c0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
2c2d0 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
2c2e0 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
2c2f0 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
2c300 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2c310 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c320 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
2c330 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
2c340 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2c350 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2c360 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
2c370 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
2c380 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
2c390 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2c3a0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
2c3b0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
2c3c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2c3d0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
2c3e0 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
2c3f0 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
2c400 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2c410 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
2c420 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2c430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2c440 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2c450 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
2c460 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c470 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2c480 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2c490 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2c4a0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
2c4b0 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
2c4c0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2c4d0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2c4e0 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2c4f0 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
2c500 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
2c510 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
2c520 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
2c530 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
2c540 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2c550 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
2c560 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
2c570 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
2c580 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
2c590 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
2c5a0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
2c5b0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2c5c0 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
2c5d0 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
2c5e0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2c5f0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2c600 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2c610 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2c620 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
2c630 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
2c640 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2c650 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2c660 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
2c670 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2c680 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
2c690 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
2c6a0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
2c6b0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2c6c0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
2c6d0 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
2c6e0 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
2c6f0 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
2c700 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
2c710 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
2c720 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
2c730 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
2c740 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
2c750 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
2c760 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
2c770 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
2c780 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2c790 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2c7a0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
2c7b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
2c7c0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2c7d0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2c7e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2c7f0 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
2c800 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2c810 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
2c820 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
2c830 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
2c840 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
2c850 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
2c860 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2c870 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
2c880 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
2c890 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
2c8a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2c8b0 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
2c8c0 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
2c8d0 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
2c8e0 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
2c8f0 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
2c900 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
2c910 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
2c920 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2c930 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
2c940 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
2c950 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
2c960 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
2c970 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
2c980 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
2c990 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
2c9a0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
2c9b0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
2c9c0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
2c9d0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
2c9e0 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
2c9f0 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
2ca00 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
2ca10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2ca20 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
2ca30 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
2ca40 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2ca50 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
2ca60 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
2ca70 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
2ca80 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
2ca90 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
2caa0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
2cab0 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
2cac0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
2cad0 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
2cae0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2caf0 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
2cb00 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
2cb10 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
2cb20 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2cb30 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2cb40 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
2cb50 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69  e "result set" i
2cb60 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2cb70 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2cb80 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2cb90 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
2cba0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
2cbb0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
2cbc0 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
2cbd0 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
2cbe0 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
2cbf0 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2cc00 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
2cc10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cc20 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
2cc30 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
2cc40 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
2cc50 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2cc60 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2cc70 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2cc80 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
2cc90 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
2cca0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2ccb0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2ccc0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
2ccd0 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
2cce0 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
2ccf0 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
2cd00 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
2cd10 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2cd20 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
2cd30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
2cd40 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2cd50 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
2cd60 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
2cd70 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
2cd80 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
2cd90 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
2cda0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2cdb0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
2cdc0 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
2cdd0 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
2cde0 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
2cdf0 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
2ce00 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
2ce10 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
2ce20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
2ce30 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
2ce40 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2ce50 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2ce60 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2ce70 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2ce80 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
2ce90 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
2cea0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
2ceb0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2cec0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
2ced0 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
2cee0 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
2cef0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2cf00 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
2cf10 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2cf20 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2cf30 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
2cf40 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
2cf50 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2cf60 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
2cf70 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2cf80 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
2cf90 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2cfa0 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
2cfb0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2cfc0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2cfd0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2cfe0 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
2cff0 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
2d000 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
2d010 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
2d020 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
2d030 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
2d040 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2d050 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2d060 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2d070 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
2d080 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2d090 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2d0a0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
2d0b0 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
2d0c0 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
2d0d0 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
2d0e0 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
2d0f0 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
2d100 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
2d110 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
2d120 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
2d130 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
2d140 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
2d150 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
2d160 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
2d170 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2d180 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
2d190 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
2d1a0 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
2d1b0 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
2d1c0 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
2d1d0 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
2d1e0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
2d1f0 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
2d200 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2d210 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2d220 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
2d230 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
2d240 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
2d250 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
2d260 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
2d270 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
2d280 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
2d290 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
2d2a0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2d2b0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2d2c0 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
2d2d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2d2e0 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
2d2f0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2d300 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2d310 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2d320 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2d330 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2d340 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
2d350 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2d360 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
2d370 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2d380 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
2d390 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2d3a0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2d3b0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2d3c0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2d3d0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2d3e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2d3f0 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
2d400 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2d410 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2d420 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2d430 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
2d440 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2d450 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2d460 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
2d470 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2d480 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
2d490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d4a0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2d4b0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
2d4c0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
2d4d0 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
2d4e0 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
2d4f0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2d500 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
2d510 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2d520 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2d530 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
2d540 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2d550 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
2d560 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
2d570 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2d580 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
2d590 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2d5a0 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
2d5b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2d5c0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
2d5d0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2d5e0 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
2d5f0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2d600 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
2d610 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
2d620 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
2d630 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
2d640 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
2d650 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2d660 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2d670 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2d680 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2d690 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2d6a0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2d6b0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2d6c0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2d6d0 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
2d6e0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2d6f0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2d700 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
2d710 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2d720 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
2d730 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
2d740 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
2d750 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
2d760 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
2d770 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
2d780 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
2d790 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2d7a0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
2d7b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d7c0 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
2d7d0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
2d7e0 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
2d7f0 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
2d800 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2d810 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
2d820 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
2d830 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2d840 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
2d850 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
2d860 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
2d870 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
2d880 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
2d890 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2d8a0 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
2d8b0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2d8c0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
2d8d0 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
2d8e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2d8f0 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74  *.** ^The object
2d900 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
2d910 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
2d920 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
2d930 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2d940 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2d950 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
2d960 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2d970 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
2d980 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
2d990 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
2d9a0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
2d9b0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
2d9c0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
2d9d0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
2d9e0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2d9f0 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2da00 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2da10 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
2da20 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
2da30 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
2da40 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
2da50 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
2da60 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
2da70 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2da80 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
2da90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
2daa0 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
2dab0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
2dac0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
2dad0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
2dae0 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
2daf0 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
2db00 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
2db10 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
2db20 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
2db30 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
2db40 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
2db50 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
2db60 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
2db70 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
2db80 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
2db90 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
2dba0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
2dbb0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
2dbc0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
2dbd0 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
2dbe0 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
2dbf0 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
2dc00 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2dc10 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
2dc20 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
2dc30 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
2dc40 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
2dc50 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
2dc60 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
2dc70 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
2dc80 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
2dc90 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
2dca0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
2dcb0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
2dcc0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2dcd0 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
2dce0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
2dcf0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
2dd00 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
2dd10 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2dd20 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2dd30 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  L    <td>   BLOB
2dd40 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2dd50 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2dd60 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e  r.** <tr><td> IN
2dd70 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f  TEGER  <td>  FLO
2dd80 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
2dd90 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20  rt from integer 
2dda0 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  to float.** <tr>
2ddb0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
2ddc0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
2ddd0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
2dde0 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72  g of the integer
2ddf0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2de00 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f  EGER  <td>   BLO
2de10 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
2de20 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a  s INTEGER->TEXT.
2de30 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2de40 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  AT   <td> INTEGE
2de50 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20  R   <td> [CAST] 
2de60 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74  to INTEGER.** <t
2de70 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
2de80 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2de90 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
2dea0 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
2deb0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2dec0 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
2ded0 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  B    <td> [CAST]
2dee0 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e   to BLOB.** <tr>
2def0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2df00 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
2df10 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45  > [CAST] to INTE
2df20 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  GER.** <tr><td> 
2df30 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46   TEXT    <td>  F
2df40 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41  LOAT    <td> [CA
2df50 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c  ST] to REAL.** <
2df60 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2df70 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2df80 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
2df90 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2dfa0 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2dfb0 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2dfc0 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2dfd0 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
2dfe0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
2dff0 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41  d> [CAST] to REA
2e000 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  L.** <tr><td>  B
2e010 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45  LOB    <td>   TE
2e020 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61  XT    <td> Add a
2e030 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2e040 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f   if needed.** </
2e050 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63  table>.** </bloc
2e060 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
2e070 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20  The table above 
2e080 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20  makes reference 
2e090 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  to standard C li
2e0a0 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20  brary functions 
2e0b0 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74  atoi().** and at
2e0c0 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f  of().  SQLite do
2e0d0 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73  es not really us
2e0e0 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  e these function
2e0f0 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a  s.  It has its.*
2e100 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74  * own equivalent
2e110 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e   internal routin
2e120 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20  es.  The atoi() 
2e130 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73  and atof() names
2e140 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20   are.** used in 
2e150 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72  the table for br
2e160 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73  evity and becaus
2e170 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c  e they are famil
2e180 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43  iar to most.** C
2e190 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a   programmers..**
2e1a0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68  .** Note that wh
2e1b0 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69  en type conversi
2e1c0 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74  ons occur, point
2e1d0 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ers returned by 
2e1e0 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  prior.** calls t
2e1f0 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  o sqlite3_column
2e200 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
2e210 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20  _column_text(), 
2e220 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  and/or.** sqlite
2e230 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2e240 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64  ) may be invalid
2e250 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f  ated..** Type co
2e260 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f  nversions and po
2e270 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69  inter invalidati
2e280 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  ons might occur.
2e290 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  ** in the follow
2e2a0 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a  ing cases:.**.**
2e2b0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
2e2c0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2e2d0 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20  t is a BLOB and 
2e2e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e2f0 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20  ext() or.**     
2e300 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e310 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c  text16() is call
2e320 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d  ed.  A zero-term
2e330 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20  inator might.** 
2e340 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20       need to be 
2e350 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72  added to the str
2e360 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69  ing.</li>.** <li
2e370 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f  > The initial co
2e380 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74  ntent is UTF-8 t
2e390 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  ext and sqlite3_
2e3a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2e3b0 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69   or.**      sqli
2e3c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2e3d0 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  6() is called.  
2e3e0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
2e3f0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
2e400 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e        to UTF-16.
2e410 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
2e420 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
2e430 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74  t is UTF-16 text
2e440 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2e450 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
2e460 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63  *      sqlite3_c
2e470 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20  olumn_text() is 
2e480 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
2e490 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
2e4a0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
2e4b0 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a  o UTF-8.</li>.**
2e4c0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f   </ul>.**.** ^Co
2e4d0 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65  nversions betwee
2e4e0 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55  n UTF-16be and U
2e4f0 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61  TF-16le are alwa
2e500 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  ys done in place
2e510 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69   and do.** not i
2e520 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f  nvalidate a prio
2e530 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67  r pointer, thoug
2e540 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20  h of course the 
2e550 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62  content of the b
2e560 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68  uffer.** that th
2e570 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20  e prior pointer 
2e580 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20  references will 
2e590 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69  have been modifi
2e5a0 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73  ed.  Other kinds
2e5b0 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f  .** of conversio
2e5c0 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c  n are done in pl
2e5d0 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70  ace when it is p
2e5e0 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d  ossible, but som
2e5f0 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61  etimes they.** a
2e600 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  re not possible 
2e610 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73  and in those cas
2e620 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  es prior pointer
2e630 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65  s are invalidate
2e640 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66  d..**.** The saf
2e650 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20  est and easiest 
2e660 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69  to remember poli
2e670 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20  cy is to invoke 
2e680 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
2e690 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  * in one of the 
2e6a0 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a  following ways:.
2e6b0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c  **.** <ul>.**  <
2e6c0 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  li>sqlite3_colum
2e6d0 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65  n_text() followe
2e6e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2e6f0 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e  umn_bytes()</li>
2e700 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33  .**  <li>sqlite3
2e710 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66  _column_blob() f
2e720 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2e730 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2e740 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  )</li>.**  <li>s
2e750 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2e760 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20  xt16() followed 
2e770 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2e780 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e  n_bytes16()</li>
2e790 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
2e7a0 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2e7b0 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20  you should call 
2e7c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e7d0 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65  ext(),.** sqlite
2e7e0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
2e7f0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2e800 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73  mn_text16() firs
2e810 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72  t to force the r
2e820 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68  esult.** into th
2e830 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74  e desired format
2e840 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71  , then invoke sq
2e850 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e860 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  es() or.** sqlit
2e870 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2e880 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20  6() to find the 
2e890 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75  size of the resu
2e8a0 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20  lt.  Do not mix 
2e8b0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69  calls.** to sqli
2e8c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2e8d0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2e8e0 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20  umn_blob() with 
2e8f0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
2e900 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e910 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74  16(), and do not
2e920 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71   mix calls to sq
2e930 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2e940 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61  t16().** with ca
2e950 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
2e960 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a  olumn_bytes()..*
2e970 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65  *.** ^The pointe
2e980 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  rs returned are 
2e990 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79  valid until a ty
2e9a0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63  pe conversion oc
2e9b0 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72  curs as.** descr
2e9c0 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75  ibed above, or u
2e9d0 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ntil [sqlite3_st
2e9e0 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2e9f0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2ea00 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2ea10 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e  ze()] is called.
2ea20 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70    ^The memory sp
2ea30 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  ace used to hold
2ea40 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20   strings.** and 
2ea50 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61  BLOBs is freed a
2ea60 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44  utomatically.  D
2ea70 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73  o <b>not</b> pas
2ea80 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72  s the pointers r
2ea90 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  eturned.** from 
2eaa0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2eab0 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
2eac0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
2ead0 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b  , etc. into.** [
2eae0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
2eaf0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65  .**.** ^(If a me
2eb00 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2eb10 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
2eb20 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69  ing the evaluati
2eb30 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  on of any.** of 
2eb40 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20  these routines, 
2eb50 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  a default value 
2eb60 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  is returned.  Th
2eb70 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a  e default value.
2eb80 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65  ** is either the
2eb90 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20   integer 0, the 
2eba0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2ebb0 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20  umber 0.0, or a 
2ebc0 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e  NULL.** pointer.
2ebd0 20 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c    Subsequent cal
2ebe0 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65  ls to [sqlite3_e
2ebf0 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72  rrcode()] will r
2ec00 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
2ec10 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51  _NOMEM].)^.*/.SQ
2ec20 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
2ec30 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  oid *sqlite3_col
2ec40 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  umn_blob(sqlite3
2ec50 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2ec60 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2ec70 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2ec80 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73  _bytes(sqlite3_s
2ec90 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2eca0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ecb0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2ecc0 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73  ytes16(sqlite3_s
2ecd0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2ece0 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62  .SQLITE_API doub
2ecf0 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  le sqlite3_colum
2ed00 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  n_double(sqlite3
2ed10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2ed20 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2ed30 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2ed40 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
2ed50 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
2ed60 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
2ed70 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
2ed80 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
2ed90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2eda0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
2edb0 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  I const unsigned
2edc0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2edd0 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
2ede0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2edf0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
2ee00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2ee10 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2ee20 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2ee30 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
2ee40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2ee50 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
2ee60 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2ee70 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
2ee80 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  API sqlite3_valu
2ee90 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  e *sqlite3_colum
2eea0 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  n_value(sqlite3_
2eeb0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2eec0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2eed0 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65  F: Destroy A Pre
2eee0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2eef0 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  Object.**.** ^Th
2ef00 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2ef10 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  ze() function is
2ef20 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74   called to delet
2ef30 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
2ef40 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66  atement]..** ^If
2ef50 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2ef60 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74   evaluation of t
2ef70 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63  he statement enc
2ef80 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f  ountered no erro
2ef90 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20  rs.** or if the 
2efa0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76  statement is nev
2efb0 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65  er been evaluate
2efc0 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  d, then sqlite3_
2efd0 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72  finalize() retur
2efe0 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e  ns.** SQLITE_OK.
2eff0 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72    ^If the most r
2f000 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2f010 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20   of statement S 
2f020 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20  failed, then.** 
2f030 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2f040 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  (S) returns the 
2f050 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
2f060 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  or code] or.** [
2f070 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
2f080 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2f090 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2f0a0 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e  e(S) routine can
2f0b0 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e   be called at an
2f0c0 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a  y point during.*
2f0d0 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65  * the life cycle
2f0e0 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2f0f0 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62  atement] S:.** b
2f100 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20  efore statement 
2f110 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61  S is ever evalua
2f120 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e  ted, after.** on
2f130 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20  e or more calls 
2f140 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
2f150 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61  t()], or after a
2f160 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73  ny call.** to [s
2f170 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72  qlite3_step()] r
2f180 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
2f190 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
2f1a0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a  statement has.**
2f1b0 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75   completed execu
2f1c0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76  tion..**.** ^Inv
2f1d0 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69  oking sqlite3_fi
2f1e0 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55  nalize() on a NU
2f1f0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20  LL pointer is a 
2f200 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
2f210 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
2f220 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c  ation must final
2f230 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61  ize every [prepa
2f240 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
2f250 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64  n order to avoid
2f260 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61  .** resource lea
2f270 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69  ks.  It is a gri
2f280 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20  evous error for 
2f290 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2f2a0 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a  to try to use.**
2f2b0 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74   a prepared stat
2f2c0 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2f2d0 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2f2e0 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61  d.  Any use of a
2f2f0 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61   prepared.** sta
2f300 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2f310 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2f320 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  ed can result in
2f330 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a   undefined and.*
2f340 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65  * undesirable be
2f350 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73  havior such as s
2f360 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61  egfaults and hea
2f370 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  p corruption..*/
2f380 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f390 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2f3a0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2f3b0 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2f3c0 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 20  PI3REF: Reset A 
2f3d0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2f3e0 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  nt Object.**.** 
2f3f0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65  The sqlite3_rese
2f400 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  t() function is 
2f410 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20  called to reset 
2f420 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2f430 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2f440 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2f450 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64  tial state, read
2f460 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75  y to be re-execu
2f470 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c  ted..** ^Any SQL
2f480 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61   statement varia
2f490 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76 61  bles that had va
2f4a0 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68  lues bound to th
2f4b0 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20  em using.** the 
2f4c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2f4d0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e  ob | sqlite3_bin
2f4e0 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69  d_*() API] retai
2f4f0 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a  n their values..
2f500 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f  ** Use [sqlite3_
2f510 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29  clear_bindings()
2f520 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 62  ] to reset the b
2f530 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e  indings..**.** ^
2f540 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
2f550 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
2f560 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72 65   resets the [pre
2f570 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f580 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68   S.** back to th
2f590 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69  e beginning of i
2f5a0 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a  ts program..**.*
2f5b0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2f5c0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2f5d0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2f5e0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2f5f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2f600 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  S returned [SQLI
2f610 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49  TE_ROW] or [SQLI
2f620 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20  TE_DONE],.** or 
2f630 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  if [sqlite3_step
2f640 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62  (S)] has never b
2f650 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65  efore been calle
2f660 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20  d on S,.** then 
2f670 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2f680 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  )] returns [SQLI
2f690 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  TE_OK]..**.** ^I
2f6a0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2f6b0 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
2f6c0 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
2f6d0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2f6e0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e   statement] S in
2f6f0 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72  dicated an error
2f700 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74  , then.** [sqlit
2f710 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74  e3_reset(S)] ret
2f720 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69  urns an appropri
2f730 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2f740 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
2f750 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2f760 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e  interface does n
2f770 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
2f780 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b  lues.** of any [
2f790 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2f7a0 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74  b|bindings] on t
2f7b0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2f7c0 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51  tement] S..*/.SQ
2f7d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2f7e0 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74  ite3_reset(sqlit
2f7f0 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b  e3_stmt *pStmt);
2f800 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f810 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65 64 65  : Create Or Rede
2f820 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f  fine SQL Functio
2f830 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ns.** KEYWORDS: 
2f840 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  {function creati
2f850 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20  on routines}.** 
2f860 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
2f870 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2f880 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20  QL function}.** 
2f890 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69  KEYWORDS: {appli
2f8a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
2f8b0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a  QL functions}.**
2f8c0 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74  .** ^These funct
2f8d0 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65  ions (collective
2f8e0 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e  ly known as "fun
2f8f0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
2f900 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65  outines").** are
2f910 20 75 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c   used to add SQL
2f920 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
2f930 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72  gregates or to r
2f940 65 64 65 66 69 6e 65 20 74 68 65 20 62 65 68 61  edefine the beha
2f950 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74  vior.** of exist
2f960 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ing SQL function
2f970 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e  s or aggregates.
2f980 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65    The only diffe
2f990 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a  rences between.*
2f9a0 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * these routines
2f9b0 20 61 72 65 20 74 68 65 20 74 65 78 74 20 65 6e   are the text en
2f9c0 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65 64 20  coding expected 
2f9d0 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  for.** the secon
2f9e0 64 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65  d parameter (the
2f9f0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e   name of the fun
2fa00 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61  ction being crea
2fa10 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ted).** and the 
2fa20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65  presence or abse
2fa30 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72 75 63  nce of a destruc
2fa40 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72  tor callback for
2fa50 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2fa60 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
2fa70 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
2fa80 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2fa90 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
2faa0 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69  nnection] to whi
2fab0 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75  ch the SQL.** fu
2fac0 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20  nction is to be 
2fad0 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61  added.  ^If an a
2fae0 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20  pplication uses 
2faf0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61  more than one da
2fb00 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
2fb10 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63  tion then applic
2fb20 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
2fb30 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74  L functions must
2fb40 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20   be added.** to 
2fb50 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
2fb60 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74  nnection separat
2fb70 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ely..**.** ^The 
2fb80 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
2fb90 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
2fba0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
2fbb0 20 74 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f   to be created o
2fbc0 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20  r.** redefined. 
2fbd0 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20   ^The length of 
2fbe0 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69  the name is limi
2fbf0 74 65 64 20 74 6f 20 32 35 35 20 62 79 74 65 73  ted to 255 bytes
2fc00 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72   in a UTF-8.** r
2fc10 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65  epresentation, e
2fc20 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20  xclusive of the 
2fc30 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e  zero-terminator.
2fc40 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65    ^Note that the
2fc50 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20   name.** length 
2fc60 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d  limit is in UTF-
2fc70 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61  8 bytes, not cha
2fc80 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d  racters nor UTF-
2fc90 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e  16 bytes.  .** ^
2fca0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63  Any attempt to c
2fcb0 72 65 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e  reate a function
2fcc0 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e   with a longer n
2fcd0 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75  ame.** will resu
2fce0 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  lt in [SQLITE_MI
2fcf0 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75  SUSE] being retu
2fd00 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
2fd10 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
2fd20 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68   (nArg).** is th
2fd30 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  e number of argu
2fd40 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65 20 53  ments that the S
2fd50 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2fd60 2a 20 61 67 67 72 65 67 61 74 65 20 74 61 6b 65  * aggregate take
2fd70 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61 72 61  s. ^If this para
2fd80 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65  meter is -1, the
2fd90 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  n the SQL functi
2fda0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
2fdb0 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20  te may take any 
2fdc0 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
2fdd0 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e  nts between 0 an
2fde0 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73  d the limit.** s
2fdf0 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  et by [sqlite3_l
2fe00 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49  imit]([SQLITE_LI
2fe10 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
2fe20 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68 69 72  ]).  If the thir
2fe30 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69  d.** parameter i
2fe40 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f  s less than -1 o
2fe50 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31  r greater than 1
2fe60 32 37 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  27 then the beha
2fe70 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66  vior is.** undef
2fe80 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2fe90 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2fea0 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73 70 65  r, eTextRep, spe
2feb0 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b  cifies what.** [
2fec0 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65  SQLITE_UTF8 | te
2fed0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69  xt encoding] thi
2fee0 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70  s SQL function p
2fef0 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74  refers for.** it
2ff00 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 45  s parameters.  E
2ff10 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74 69 6f  very SQL functio
2ff20 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2ff30 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20 74 6f   must be able to
2ff40 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54   work.** with UT
2ff50 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f  F-8, UTF-16le, o
2ff60 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42 75 74  r UTF-16be.  But
2ff70 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61   some implementa
2ff80 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20  tions may be.** 
2ff90 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 77  more efficient w
2ffa0 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67  ith one encoding
2ffb0 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20   than another.  
2ffc0 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ^An application 
2ffd0 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71  may.** invoke sq
2ffe0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2fff0 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74  ction() or sqlit
30000 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
30010 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a  on16() multiple.
30020 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20 74 68  ** times with th
30030 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
30040 62 75 74 20 77 69 74 68 20 64 69 66 66 65 72 65  but with differe
30050 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65 54 65  nt values of eTe
30060 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20  xtRep..** ^When 
30070 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
30080 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
30090 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 61 72  same function ar
300a0 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c  e available, SQL
300b0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b  ite.** will pick
300c0 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20 69 6e   the one that in
300d0 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61 73 74  volves the least
300e0 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20   amount of data 
300f0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49  conversion..** I
30100 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c 79 20  f there is only 
30110 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65  a single impleme
30120 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20 64 6f  ntation which do
30130 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68 61 74  es not care what
30140 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e   text.** encodin
30150 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20  g is used, then 
30160 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
30170 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 5b 53  ent should be [S
30180 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a  QLITE_ANY]..**.*
30190 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61  * ^(The fifth pa
301a0 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72  rameter is an ar
301b0 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e  bitrary pointer.
301c0 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61    The implementa
301d0 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66  tion of the.** f
301e0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e  unction can gain
301f0 20 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20   access to this 
30200 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73  pointer using [s
30210 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
30220 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ()].)^.**.** ^Th
30230 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68  e sixth, seventh
30240 20 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61   and eighth para
30250 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78  meters, xFunc, x
30260 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c  Step and xFinal,
30270 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73   are.** pointers
30280 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66   to C-language f
30290 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d  unctions that im
302a0 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
302b0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
302c0 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61  ggregate. ^A sca
302d0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
302e0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
302f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
30300 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c  he xFunc.** call
30310 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20  back only; NULL 
30320 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65  pointers must be
30330 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78   passed as the x
30340 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a  Step and xFinal.
30350 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e  ** parameters. ^
30360 41 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c  An aggregate SQL
30370 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
30380 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  es an implementa
30390 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a  tion of xStep.**
303a0 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20   and xFinal and 
303b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73  NULL pointer mus
303c0 74 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20  t be passed for 
303d0 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74  xFunc. ^To delet
303e0 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a  e an existing.**
303f0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
30400 20 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73   aggregate, pass
30410 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66   NULL pointers f
30420 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e  or all three fun
30430 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ction.** callbac
30440 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  ks..**.** ^(If t
30450 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74  he ninth paramet
30460 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
30470 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
30480 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a  () is not NULL,.
30490 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65  ** then it is de
304a0 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
304b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
304c0 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54  a pointer. .** T
304d0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
304e0 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68   invoked when th
304f0 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65  e function is de
30500 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79  leted, either by
30510 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f   being.** overlo
30520 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65  aded or when the
30530 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
30540 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a  tion closes.)^.*
30550 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f  * ^The destructo
30560 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65  r is also invoke
30570 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f  d if the call to
30580 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
30590 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29  te_function_v2()
305a0 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e   fails..** ^When
305b0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
305c0 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  callback of the 
305d0 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  tenth parameter 
305e0 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a  is invoked, it.*
305f0 2a 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69  * is passed a si
30600 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
30610 69 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ich is a copy of
30620 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
30630 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65   data .** pointe
30640 72 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20  r which was the 
30650 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
30660 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
30670 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e  e_function_v2().
30680 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65  .**.** ^It is pe
30690 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73  rmitted to regis
306a0 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  ter multiple imp
306b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
306c0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63  the same.** func
306d0 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73  tions with the s
306e0 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74  ame name but wit
306f0 68 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69  h either differi
30700 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a  ng numbers of.**
30710 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69   arguments or di
30720 66 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65  ffering preferre
30730 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  d text encodings
30740 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  .  ^SQLite will 
30750 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65  use.** the imple
30760 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d  mentation that m
30770 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63  ost closely matc
30780 68 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77  hes the way in w
30790 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20  hich the.** SQL 
307a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64  function is used
307b0 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69  .  ^A function i
307c0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
307d0 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  th a non-negativ
307e0 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65  e.** nArg parame
307f0 74 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20  ter is a better 
30800 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
30810 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
30820 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e  tion with.** a n
30830 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e  egative nArg.  ^
30840 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
30850 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74   the preferred t
30860 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20  ext encoding.** 
30870 6d 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61  matches the data
30880 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  base encoding is
30890 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74   a better.** mat
308a0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
308b0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
308c0 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65  oding is differe
308d0 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63  nt.  .** ^A func
308e0 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
308f0 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e  ncoding differen
30900 63 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54  ce is between UT
30910 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62  F16le and UTF16b
30920 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72  e.** is a closer
30930 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
30940 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
30950 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
30960 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65  ence is.** betwe
30970 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31  en UTF8 and UTF1
30980 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d  6..**.** ^Built-
30990 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  in functions may
309a0 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62   be overloaded b
309b0 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f  y new applicatio
309c0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
309d0 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61  ons..**.** ^An a
309e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
309f0 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70  ed function is p
30a00 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c  ermitted to call
30a10 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
30a20 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f   interfaces.  Ho
30a30 77 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c  wever, such call
30a40 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c  s must not.** cl
30a50 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
30a60 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20   connection nor 
30a70 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65  finalize or rese
30a80 74 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a  t the prepared.*
30a90 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77  * statement in w
30aa0 68 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f  hich the functio
30ab0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
30ac0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
30ad0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30ae0 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  unction(.  sqlit
30af0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
30b00 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
30b10 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
30b20 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
30b30 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
30b40 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
30b50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30b60 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
30b70 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
30b80 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
30b90 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
30ba0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
30bb0 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
30bc0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
30bd0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
30be0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
30bf0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
30c00 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
30c10 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
30c20 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
30c30 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
30c40 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
30c50 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
30c60 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
30c70 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
30c80 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
30c90 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
30ca0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
30cb0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
30cc0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
30cd0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
30ce0 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  t*).);.SQLITE_AP
30cf0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
30d00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
30d10 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
30d20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
30d30 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20  FunctionName,.  
30d40 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20  int nArg,.  int 
30d50 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64  eTextRep,.  void
30d60 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28   *pApp,.  void (
30d70 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xFunc)(sqlite3_
30d80 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
30d90 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
30da0 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73   void (*xStep)(s
30db0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30dc0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
30dd0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
30de0 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63  Final)(sqlite3_c
30df0 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64  ontext*),.  void
30e00 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64  (*xDestroy)(void
30e10 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *).);../*.** CAP
30e20 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f  I3REF: Text Enco
30e30 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  dings.**.** Thes
30e40 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e  e constant defin
30e50 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20  e integer codes 
30e60 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20 74  that represent t
30e70 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65  he various.** te
30e80 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70  xt encodings sup
30e90 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
30ea0 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
30eb0 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20 20  ITE_UTF8        
30ec0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
30ed0 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20  ITE_UTF16LE     
30ee0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
30ef0 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20 20  ITE_UTF16BE     
30f00 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
30f10 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20 20  ITE_UTF16       
30f20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e     4    /* Use n
30f30 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
30f40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
30f50 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20  TE_ANY          
30f60 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74 65    5    /* sqlite
30f70 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
30f80 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  n only */.#defin
30f90 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41  e SQLITE_UTF16_A
30fa0 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a 20  LIGNED  8    /* 
30fb0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
30fc0 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  ollation only */
30fd0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
30fe0 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e  : Deprecated Fun
30ff0 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43  ctions.** DEPREC
31000 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ATED.**.** These
31010 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b   functions are [
31020 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e  deprecated].  In
31030 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61   order to mainta
31040 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  in.** backwards 
31050 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69  compatibility wi
31060 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74  th older code, t
31070 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63  hese functions c
31080 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62  ontinue .** to b
31090 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f  e supported.  Ho
310a0 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69  wever, new appli
310b0 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61  cations should a
310c0 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20  void.** the use 
310d0 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  of these functio
310e0 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63  ns.  To help enc
310f0 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f  ourage people to
31100 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20   avoid.** using 
31110 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c  these functions,
31120 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e   we are not goin
31130 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68  g to tell you wh
31140 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23  at they do..*/.#
31150 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  ifndef SQLITE_OM
31160 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51  IT_DEPRECATED.SQ
31170 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
31180 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
31190 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
311a0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 63  _count(sqlite3_c
311b0 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45  ontext*);.SQLITE
311c0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
311d0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
311e0 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74  e3_expired(sqlit
311f0 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54  e3_stmt*);.SQLIT
31200 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
31210 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
31220 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
31230 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
31240 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
31250 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
31260 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
31270 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c  D int sqlite3_gl
31280 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69  obal_recover(voi
31290 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
312a0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
312b0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68   void sqlite3_th
312c0 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69  read_cleanup(voi
312d0 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53  d);.SQLITE_API S
312e0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
312f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
31300 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
31310 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
31320 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20  int64,int),.    
31330 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31340 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f    void*,sqlite3_
31350 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
31360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31370 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
31380 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
31390 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68   Values.**.** Th
313a0 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
313b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
313c0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
313d0 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
313e0 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
313f0 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
31400 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
31410 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
31420 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
31430 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
31440 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
31450 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
31460 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
31470 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
31480 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
31490 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
314a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
314b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
314c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
314d0 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
314e0 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
314f0 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
31500 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
31510 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
31520 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
31530 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
31540 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
31550 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
31560 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
31570 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
31580 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
31590 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
315a0 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
315b0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
315c0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
315d0 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
315e0 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
315f0 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
31600 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
31610 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
31620 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
31630 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
31640 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
31650 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
31660 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
31670 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
31680 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
31690 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
316a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
316b0 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
316c0 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
316d0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
316e0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
316f0 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
31700 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
31710 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
31720 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
31730 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72  pt that  these r
31740 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
31750 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
31760 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
31770 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
31780 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
31790 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
317a0 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
317b0 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
317c0 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
317d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
317e0 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
317f0 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
31800 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
31810 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
31820 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
31830 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
31840 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
31850 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
31860 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
31870 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
31880 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
31890 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
318a0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
318b0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
318c0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
318d0 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
318e0 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
318f0 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
31900 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
31910 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
31920 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
31930 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
31940 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
31950 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
31960 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
31970 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
31980 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
31990 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
319a0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
319b0 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
319c0 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
319d0 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
319e0 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
319f0 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
31a00 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
31a10 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
31a20 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
31a30 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
31a40 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
31a50 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
31a60 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
31a70 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
31a80 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
31a90 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
31aa0 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
31ab0 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
31ac0 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
31ad0 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
31ae0 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
31af0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
31b00 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
31b10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
31b20 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
31b30 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
31b40 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
31b50 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
31b60 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
31b70 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
31b80 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
31b90 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
31ba0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
31bb0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
31bc0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
31bd0 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
31be0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
31bf0 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
31c00 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
31c10 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
31c20 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
31c30 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
31c40 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
31c50 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
31c60 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
31c70 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31c80 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
31c90 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
31ca0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
31cb0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
31cc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31cd0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31ce0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
31cf0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
31d00 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
31d10 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
31d20 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
31d30 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
31d40 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
31d50 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
31d60 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31d70 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
31d80 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
31d90 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
31da0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
31db0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
31dc0 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
31dd0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
31de0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
31df0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
31e00 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31e10 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
31e20 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
31e30 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
31e40 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
31e50 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
31e60 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
31e70 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
31e80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
31e90 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
31ea0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
31eb0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
31ec0 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
31ed0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
31ee0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31ef0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
31f00 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
31f10 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
31f20 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
31f30 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
31f40 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
31f50 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
31f60 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
31f70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
31f80 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
31f90 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
31fa0 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
31fb0 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
31fc0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
31fd0 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
31fe0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
31ff0 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
32000 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
32010 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
32020 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
32030 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
32040 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
32050 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
32060 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
32070 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
32080 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
32090 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
320a0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
320b0 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
320c0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
320d0 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
320e0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
320f0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
32100 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
32110 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
32120 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
32130 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
32140 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
32150 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
32160 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
32170 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
32180 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
32190 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
321a0 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
321b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
321c0 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
321d0 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
321e0 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
321f0 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
32200 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
32210 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
32220 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
32230 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
32240 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
32250 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
32260 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
32270 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
32280 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
32290 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
322a0 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
322b0 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
322c0 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
322d0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
322e0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
322f0 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
32300 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
32310 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a   NULL pointer .*
32320 2a 20 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c  * when first cal
32330 6c 65 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73  led if N is less
32340 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
32350 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d  o zero or if a m
32360 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
32370 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
32380 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
32390 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
323a0 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
323b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
323c0 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
323d0 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
323e0 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
323f0 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
32400 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
32410 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
32420 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
32430 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
32440 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
32450 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
32460 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
32470 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
32480 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
32490 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
324a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20   allocation.)^  
324b0 57 69 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61  Within the xFina
324c0 6c 20 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69  l callback, it i
324d0 73 20 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73  s customary to s
324e0 65 74 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c  et.** N=0 in cal
324f0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ls to sqlite3_ag
32500 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
32510 43 2c 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20  C,N) so that no 
32520 0a 2a 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65  .** pointless me
32530 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
32540 20 6f 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53   occur..**.** ^S
32550 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
32560 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d 65  lly frees the me
32570 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62  mory allocated b
32580 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  y .** sqlite3_ag
32590 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
325a0 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72 65  ) when the aggre
325b0 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c  gate query concl
325c0 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  udes..**.** The 
325d0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
325e0 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f  must be a copy o
325f0 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
32600 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20  3_context | SQL 
32610 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74  function context
32620 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66 69  ] that is the fi
32630 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  rst parameter.**
32640 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72   to the xStep or
32650 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
32660 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d   routine that im
32670 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67  plements the agg
32680 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69  regate.** functi
32690 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72  on..**.** This r
326a0 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63  outine must be c
326b0 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73  alled from the s
326c0 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68  ame thread in wh
326d0 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65  ich.** the aggre
326e0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
326f0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
32700 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
32710 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
32720 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
32730 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
32740 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
32750 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
32760 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
32770 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
32780 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
32790 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
327a0 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
327b0 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
327c0 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
327d0 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
327e0 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
327f0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
32800 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32810 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
32820 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32830 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
32840 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
32850 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
32860 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
32870 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
32880 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
32890 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
328a0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
328b0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
328c0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
328d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
328e0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
328f0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
32900 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
32910 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
32920 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
32930 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
32940 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
32950 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
32960 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
32970 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
32980 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
32990 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
329a0 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
329b0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
329c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
329d0 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
329e0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
329f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
32a00 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
32a10 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
32a20 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
32a30 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
32a40 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
32a50 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
32a60 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
32a70 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  function..*/.SQL
32a80 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20  ITE_API sqlite3 
32a90 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  *sqlite3_context
32aa0 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74  _db_handle(sqlit
32ab0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
32ac0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
32ad0 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72  unction Auxiliar
32ae0 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65  y Data.**.** The
32af0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  se functions may
32b00 20 62 65 20 75 73 65 64 20 62 79 20 28 6e 6f 6e   be used by (non
32b10 2d 61 67 67 72 65 67 61 74 65 29 20 53 51 4c 20  -aggregate) SQL 
32b20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20  functions to.** 
32b30 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61  associate metada
32b40 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74  ta with argument
32b50 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20   values. If the 
32b60 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61  same value is pa
32b70 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69  ssed to.** multi
32b80 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  ple invocations 
32b90 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20  of the same SQL 
32ba0 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20  function during 
32bb0 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c  query execution,
32bc0 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63   under.** some c
32bd0 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65  ircumstances the
32be0 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61   associated meta
32bf0 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73  data may be pres
32c00 65 72 76 65 64 2e 20 20 41 6e 20 65 78 61 6d 70  erved.  An examp
32c10 6c 65 0a 2a 2a 20 6f 66 20 77 68 65 72 65 20 74  le.** of where t
32c20 68 69 73 20 6d 69 67 68 74 20 62 65 20 75 73 65  his might be use
32c30 66 75 6c 20 69 73 20 69 6e 20 61 20 72 65 67 75  ful is in a regu
32c40 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
32c50 61 74 63 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74  atching.** funct
32c60 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65  ion. The compile
32c70 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  d version of the
32c80 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
32c90 69 6f 6e 20 63 61 6e 20 62 65 20 73 74 6f 72 65  ion can be store
32ca0 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
32cb0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
32cc0 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74 72   the pattern str
32cd0 69 6e 67 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61  ing.  .** Then a
32ce0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 70 61  s long as the pa
32cf0 74 74 65 72 6e 20 73 74 72 69 6e 67 20 72 65 6d  ttern string rem
32d00 61 69 6e 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a  ains the same,.*
32d10 2a 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 20 72  * the compiled r
32d20 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
32d30 6e 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20  n can be reused 
32d40 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69  on multiple.** i
32d50 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
32d60 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e  e same function.
32d70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32d80 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
32d90 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
32da0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
32db0 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a   the metadata.**
32dc0 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20 74   associated by t
32dd0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
32de0 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f  uxdata() functio
32df0 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20 61  n with the Nth a
32e00 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65  rgument.** value
32e10 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
32e20 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
32e30 74 69 6f 6e 2e 20 5e 49 66 20 74 68 65 72 65 20  tion. ^If there 
32e40 69 73 20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a  is no metadata.*
32e50 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
32e60 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 61  h the function a
32e70 72 67 75 6d 65 6e 74 2c 20 74 68 69 73 20 73 71  rgument, this sq
32e80 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
32e90 61 28 29 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  a() interface.**
32ea0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
32eb0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
32ec0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
32ed0 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
32ee0 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73   interface saves
32ef0 20 50 20 61 73 20 6d 65 74 61 64 61 74 61 20 66   P as metadata f
32f00 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61  or the N-th.** a
32f10 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 61  rgument of the a
32f20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
32f30 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53  ed function.  ^S
32f40 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
32f50 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
32f60 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 29 20 72  t_auxdata(C,N) r
32f70 65 74 75 72 6e 20 50 20 66 72 6f 6d 20 74 68 65  eturn P from the
32f80 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20   most recent.** 
32f90 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
32fa0 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c  ata(C,N,P,X) cal
32fb0 6c 20 69 66 20 74 68 65 20 6d 65 74 61 64 61 74  l if the metadat
32fc0 61 20 69 73 20 73 74 69 6c 6c 20 76 61 6c 69 64  a is still valid
32fd0 20 6f 72 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74   or.** NULL if t
32fe0 68 65 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  he metadata has 
32ff0 62 65 65 6e 20 64 69 73 63 61 72 64 65 64 2e 0a  been discarded..
33000 2a 2a 20 5e 41 66 74 65 72 20 65 61 63 68 20 63  ** ^After each c
33010 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
33020 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c 50  et_auxdata(C,N,P
33030 2c 58 29 20 77 68 65 72 65 20 58 20 69 73 20 6e  ,X) where X is n
33040 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69  ot NULL,.** SQLi
33050 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
33060 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 66 75  he destructor fu
33070 6e 63 74 69 6f 6e 20 58 20 77 69 74 68 20 70 61  nction X with pa
33080 72 61 6d 65 74 65 72 20 50 20 65 78 61 63 74 6c  rameter P exactl
33090 79 0a 2a 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20  y.** once, when 
330a0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
330b0 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51  discarded..** SQ
330c0 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
330d0 64 69 73 63 61 72 64 20 74 68 65 20 6d 65 74 61  discard the meta
330e0 64 61 74 61 20 61 74 20 61 6e 79 20 74 69 6d 65  data at any time
330f0 2c 20 69 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c  , including: <ul
33100 3e 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74  >.** <li> when t
33110 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
33120 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
33130 74 65 72 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a  ter changes, or.
33140 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71  ** <li> when [sq
33150 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
33160 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
33170 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
33180 20 66 6f 72 20 74 68 65 0a 2a 2a 20 20 20 20 20   for the.**     
33190 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
331a0 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20  or.** <li> when 
331b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
331c0 61 74 61 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ata() is invoked
331d0 20 61 67 61 69 6e 20 6f 6e 20 74 68 65 20 73 61   again on the sa
331e0 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 6f 72  me parameter, or
331f0 0a 2a 2a 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20  .** <li> during 
33200 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c  the original sql
33210 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33220 28 29 20 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d  () call when a m
33230 65 6d 6f 72 79 20 0a 2a 2a 20 20 20 20 20 20 61  emory .**      a
33240 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
33250 6f 63 63 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a  occurs. </ul>)^.
33260 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c  **.** Note the l
33270 61 73 74 20 62 75 6c 6c 65 74 20 69 6e 20 70 61  ast bullet in pa
33280 72 74 69 63 75 6c 61 72 2e 20 20 54 68 65 20 64  rticular.  The d
33290 65 73 74 72 75 63 74 6f 72 20 58 20 69 6e 20 0a  estructor X in .
332a0 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
332b0 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20  uxdata(C,N,P,X) 
332c0 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
332d0 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62 65 66  immediately, bef
332e0 6f 72 65 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74  ore the.** sqlit
332f0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
33300 20 69 6e 74 65 72 66 61 63 65 20 65 76 65 6e 20   interface even 
33310 72 65 74 75 72 6e 73 2e 20 20 48 65 6e 63 65 20  returns.  Hence 
33320 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
33330 61 74 61 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20  ata().** should 
33340 62 65 20 63 61 6c 6c 65 64 20 6e 65 61 72 20 74  be called near t
33350 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 75  he end of the fu
33360 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
33370 61 74 69 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a  ation and the.**
33380 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
33390 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  entation should 
333a0 6e 6f 74 20 6d 61 6b 65 20 61 6e 79 20 75 73 65  not make any use
333b0 20 6f 66 20 50 20 61 66 74 65 72 0a 2a 2a 20 73   of P after.** s
333c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
333d0 74 61 28 29 20 68 61 73 20 62 65 65 6e 20 63 61  ta() has been ca
333e0 6c 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e  lled..**.** ^(In
333f0 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64   practice, metad
33400 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64  ata is preserved
33410 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f   between functio
33420 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66  n calls for.** f
33430 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
33440 72 73 20 74 68 61 74 20 61 72 65 20 63 6f 6d 70  rs that are comp
33450 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e  ile-time constan
33460 74 73 2c 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69  ts, including li
33470 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
33480 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
33490 20 61 6e 64 20 65 78 70 72 65 73 73 69 6f 6e 73   and expressions
334a0 20 63 6f 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74   composed from t
334b0 68 65 20 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a  he same.)^.**.**
334c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
334d0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
334e0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
334f0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
33500 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
33510 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
33520 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
33530 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
33540 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
33550 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53  text*, int N);.S
33560 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
33570 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33580 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
33590 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
335a0 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
335b0 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
335c0 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
335d0 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
335e0 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
335f0 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
33600 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
33610 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
33620 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
33630 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
33640 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
33650 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
33660 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
33670 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
33680 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
33690 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
336a0 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
336b0 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
336c0 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
336d0 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
336e0 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
336f0 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
33700 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
33710 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
33720 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
33730 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
33740 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
33750 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
33760 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
33770 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
33780 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
33790 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
337a0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
337b0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
337c0 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
337d0 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
337e0 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
337f0 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
33800 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
33810 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
33820 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f  s..*/.typedef vo
33830 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73  id (*sqlite3_des
33840 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f  tructor_type)(vo
33850 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51  id*);.#define SQ
33860 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20 20 20  LITE_STATIC     
33870 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
33880 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64  uctor_type)0).#d
33890 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
338a0 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74  NSIENT   ((sqlit
338b0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
338c0 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  pe)-1)../*.** CA
338d0 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20  PI3REF: Setting 
338e0 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e  The Result Of An
338f0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a   SQL Function.**
33900 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
33910 65 73 20 61 72 65 20 75 73 65 64 20 62 79 20 74  es are used by t
33920 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e  he xFunc or xFin
33930 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  al callbacks tha
33940 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53  t.** implement S
33950 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
33960 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 53 65   aggregates.  Se
33970 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  e.** [sqlite3_cr
33980 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
33990 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
339a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
339b0 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69  )].** for additi
339c0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
339d0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  ..**.** These fu
339e0 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72  nctions work ver
339f0 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20  y much like the 
33a00 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  [parameter bindi
33a10 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a  ng] family of.**
33a20 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20   functions used 
33a30 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74  to bind values t
33a40 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  o host parameter
33a50 73 20 69 6e 20 70 72 65 70 61 72 65 64 20 73 74  s in prepared st
33a60 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66  atements..** Ref
33a70 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70  er to the [SQL p
33a80 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65  arameter] docume
33a90 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
33aa0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
33ab0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  on..**.** ^The s
33ac0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
33ad0 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ob() interface s
33ae0 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
33af0 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
33b00 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
33b10 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
33b20 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74   BLOB whose cont
33b30 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a  ent is pointed.*
33b40 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f  * to by the seco
33b50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
33b60 20 77 68 69 63 68 20 69 73 20 4e 20 62 79 74 65   which is N byte
33b70 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69  s long where N i
33b80 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  s the.** third p
33b90 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
33ba0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
33bb0 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69  ult_zeroblob() i
33bc0 6e 74 65 72 66 61 63 65 73 20 73 65 74 20 74 68  nterfaces set th
33bd0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
33be0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
33bf0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
33c00 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e  to be a BLOB con
33c10 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f  taining all zero
33c20 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20  .** bytes and N 
33c30 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77  bytes in size, w
33c40 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 76 61  here N is the va
33c50 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70  lue of the 2nd p
33c60 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
33c70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
33c80 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74  ult_double() int
33c90 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
33ca0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
33cb0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
33cc0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
33cd0 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20  o be a floating 
33ce0 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63  point value spec
33cf0 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20  ified.** by its 
33d00 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  2nd argument..**
33d10 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33d20 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
33d30 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
33d40 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e  lt_error16() fun
33d50 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20  ctions.** cause 
33d60 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  the implemented 
33d70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
33d80 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69  throw an excepti
33d90 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  on..** ^SQLite u
33da0 73 65 73 20 74 68 65 20 73 74 72 69 6e 67 20 70  ses the string p
33db0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
33dc0 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65  .** 2nd paramete
33dd0 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73  r of sqlite3_res
33de0 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73  ult_error() or s
33df0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
33e00 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68  ror16().** as th
33e10 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72  e text of an err
33e20 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51  or message.  ^SQ
33e30 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
33e40 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
33e50 73 61 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d  sage string from
33e60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
33e70 65 72 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38  error() as UTF-8
33e80 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74  . ^SQLite.** int
33e90 65 72 70 72 65 74 73 20 74 68 65 20 73 74 72 69  erprets the stri
33ea0 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
33eb0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
33ec0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61   as UTF-16 in na
33ed0 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64  tive.** byte ord
33ee0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69  er.  ^If the thi
33ef0 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
33f00 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
33f10 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
33f20 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
33f30 72 31 36 28 29 20 69 73 20 6e 65 67 61 74 69 76  r16() is negativ
33f40 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
33f50 6b 65 73 20 61 73 20 74 68 65 20 65 72 72 6f 72  kes as the error
33f60 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20  .** message all 
33f70 74 65 78 74 20 75 70 20 74 68 72 6f 75 67 68 20  text up through 
33f80 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63  the first zero c
33f90 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66  haracter..** ^If
33fa0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
33fb0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
33fc0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
33fd0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  r.** sqlite3_res
33fe0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
33ff0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68   non-negative th
34000 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
34010 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74  that many.** byt
34020 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
34030 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  rs) from the 2nd
34040 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
34050 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  e error message.
34060 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34070 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
34080 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  and sqlite3_resu
34090 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
340a0 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20  routines make a 
340b0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
340c0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
340d0 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a  e text before.**
340e0 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48   they return.  H
340f0 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e  ence, the callin
34100 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64  g function can d
34110 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20  eallocate or.** 
34120 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78 74 20  modify the text 
34130 61 66 74 65 72 20 74 68 65 79 20 72 65 74 75 72  after they retur
34140 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  n without harm..
34150 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34160 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64  result_error_cod
34170 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61  e() function cha
34180 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72 20 63  nges the error c
34190 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  ode.** returned 
341a0 62 79 20 53 51 4c 69 74 65 20 61 73 20 61 20 72  by SQLite as a r
341b0 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f  esult of an erro
341c0 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  r in a function.
341d0 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a    ^By default,.*
341e0 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  * the error code
341f0 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52   is SQLITE_ERROR
34200 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74  .  ^A subsequent
34210 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
34220 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
34230 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
34240 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72  sult_error16() r
34250 65 73 65 74 73 20 74 68 65 20 65 72 72 6f 72 20  esets the error 
34260 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45  code to SQLITE_E
34270 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  RROR..**.** ^The
34280 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34290 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69  error_toobig() i
342a0 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
342b0 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
342c0 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
342d0 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
342e0 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
342f0 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
34300 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
34310 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
34320 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69  _error_nomem() i
34330 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
34340 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
34350 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69  an.** error indi
34360 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65  cating that a me
34370 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
34380 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  failed..**.** ^T
34390 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
343a0 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63  t_int() interfac
343b0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
343c0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
343d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
343e0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
343f0 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69 74 20  o be the 32-bit 
34400 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a  signed integer.*
34410 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e  * value given in
34420 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e   the 2nd argumen
34430 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  t..** ^The sqlit
34440 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28  e3_result_int64(
34450 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
34460 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
34470 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
34480 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34490 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
344a0 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  he 64-bit signed
344b0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
344c0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
344d0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
344e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
344f0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e  result_null() in
34500 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
34510 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a   return value.**
34520 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
34530 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34540 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e  tion to be NULL.
34550 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34560 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
34570 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ), sqlite3_resul
34580 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73  t_text16(),.** s
34590 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
345a0 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71  xt16le(), and sq
345b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
345c0 74 31 36 62 65 28 29 20 69 6e 74 65 72 66 61 63  t16be() interfac
345d0 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65  es.** set the re
345e0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
345f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
34600 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
34610 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73  o be.** a text s
34620 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 20 72  tring which is r
34630 65 70 72 65 73 65 6e 74 65 64 20 61 73 20 55 54  epresented as UT
34640 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69  F-8, UTF-16 nati
34650 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a  ve byte order,.*
34660 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20  * UTF-16 little 
34670 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31  endian, or UTF-1
34680 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65  6 big endian, re
34690 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
346a0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65  SQLite takes the
346b0 20 74 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f   text result fro
346c0 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  m the applicatio
346d0 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e  n from.** the 2n
346e0 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74  d parameter of t
346f0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34700 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
34710 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33  es..** ^If the 3
34720 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
34730 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
34740 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
34750 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69  ces.** is negati
34760 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ve, then SQLite 
34770 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78  takes result tex
34780 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  t from the 2nd p
34790 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f  arameter.** thro
347a0 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
347b0 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
347c0 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
347d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
347e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
347f0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
34800 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
34810 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62  , then as many b
34820 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
34830 74 65 72 73 29 20 6f 66 20 74 68 65 20 74 65 78  ters) of the tex
34840 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  t.** pointed to 
34850 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
34860 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61  eter are taken a
34870 73 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  s the applicatio
34880 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e  n-defined.** fun
34890 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49  ction result.  I
348a0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
348b0 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  ter is non-negat
348c0 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20  ive, then it.** 
348d0 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
348e0 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65   offset into the
348f0 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 74 68   string where th
34900 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72  e NUL terminator
34910 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72   would.** appear
34920 20 69 66 20 74 68 65 20 73 74 72 69 6e 67 20 77   if the string w
34930 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61  here NUL termina
34940 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
34950 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
34960 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69  r.** in the stri
34970 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f 66 66  ng at a byte off
34980 73 65 74 20 74 68 61 74 20 69 73 20 6c 65 73 73  set that is less
34990 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20   than the value 
349a0 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61  of the 3rd.** pa
349b0 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68  rameter, then th
349c0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
349d0 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20  ng will contain 
349e0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e  embedded NULs an
349f0 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  d the.** result 
34a00 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f  of expressions o
34a10 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69  perating on stri
34a20 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64 64 65  ngs with embedde
34a30 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69  d NULs is undefi
34a40 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
34a50 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
34a60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
34a70 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
34a80 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  aces.** or sqlit
34a90 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69  e3_result_blob i
34aa0 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69  s a non-NULL poi
34ab0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
34ac0 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20  e calls that.** 
34ad0 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20  function as the 
34ae0 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68  destructor on th
34af0 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
34b00 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61  esult when it ha
34b10 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73  s.** finished us
34b20 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e  ing that result.
34b30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20  .** ^If the 4th 
34b40 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
34b50 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34b60 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
34b70 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65   or to.** sqlite
34b80 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
34b90 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
34ba0 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41  stant SQLITE_STA
34bb0 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  TIC, then SQLite
34bc0 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74  .** assumes that
34bd0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
34be0 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63  B result is in c
34bf0 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e  onstant space an
34c00 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f  d does not.** co
34c10 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  py the content o
34c20 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
34c30 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72  nor call a destr
34c40 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e  uctor on the con
34c50 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20  tent.** when it 
34c60 68 61 73 20 66 69 6e 69 73 68 65 64 20 75 73 69  has finished usi
34c70 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a  ng that result..
34c80 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70  ** ^If the 4th p
34c90 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
34ca0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34cb0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
34cc0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
34cd0 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65  sult_blob is the
34ce0 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e   special constan
34cf0 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45  t SQLITE_TRANSIE
34d00 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74  NT.** then SQLit
34d10 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
34d20 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74  f the result int
34d30 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64  o space obtained
34d40 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73   from.** from [s
34d50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
34d60 20 62 65 66 6f 72 65 20 69 74 20 72 65 74 75 72   before it retur
34d70 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
34d80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
34d90 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
34da0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
34db0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
34dc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34dd0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63  nction to be a c
34de0 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72  opy the.** [unpr
34df0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
34e00 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70  value] object sp
34e10 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 32  ecified by the 2
34e20 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e  nd parameter.  ^
34e30 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  The.** sqlite3_r
34e40 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
34e50 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20  terface makes a 
34e60 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c  copy of the [sql
34e70 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73  ite3_value].** s
34e80 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69  o that the [sqli
34e90 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69  te3_value] speci
34ea0 66 69 65 64 20 69 6e 20 74 68 65 20 70 61 72 61  fied in the para
34eb0 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65  meter may change
34ec0 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f   or.** be deallo
34ed0 63 61 74 65 64 20 61 66 74 65 72 20 73 71 6c 69  cated after sqli
34ee0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
34ef0 28 29 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  () returns witho
34f00 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b  ut harm..** ^A [
34f10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
34f20 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
34f30 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20 75 73  may always be us
34f40 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b  ed where an.** [
34f50 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
34f60 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
34f70 74 20 69 73 20 72 65 71 75 69 72 65 64 2c 20 73  t is required, s
34f80 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64  o either.** kind
34f90 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   of [sqlite3_val
34fa0 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62  ue] object can b
34fb0 65 20 75 73 65 64 20 77 69 74 68 20 74 68 69 73  e used with this
34fc0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
34fd0 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75 74 69  * If these routi
34fe0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66  nes are called f
34ff0 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64  rom within the d
35000 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a  ifferent thread.
35010 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20  ** than the one 
35020 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61  containing the a
35030 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35040 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ed function that
35050 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65   received.** the
35060 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
35070 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20  t] pointer, the 
35080 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
35090 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45  fined..*/.SQLITE
350a0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
350b0 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71  3_result_blob(sq
350c0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
350d0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
350e0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
350f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
35100 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35110 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  t_double(sqlite3
35120 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c  _context*, doubl
35130 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  e);.SQLITE_API v
35140 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35150 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33  lt_error(sqlite3
35160 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74  _context*, const
35170 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51   char*, int);.SQ
35180 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
35190 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
351a0 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e  or16(sqlite3_con
351b0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
351c0 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45  d*, int);.SQLITE
351d0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
351e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
351f0 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
35200 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  ntext*);.SQLITE_
35210 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
35220 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
35230 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
35240 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
35250 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
35260 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
35270 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35280 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
35290 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
352a0 5f 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69  _result_int(sqli
352b0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
352c0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  t);.SQLITE_API v
352d0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
352e0 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
352f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
35300 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  e3_int64);.SQLIT
35310 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
35320 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73  e3_result_null(s
35330 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
35340 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35350 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35360 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  _text(sqlite3_co
35370 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
35380 61 72 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  ar*, int, void(*
35390 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
353a0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
353b0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
353c0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
353d0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
353e0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
353f0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
35400 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
35410 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71  sult_text16le(sq
35420 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35430 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
35440 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29  ,void(*)(void*))
35450 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
35460 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35470 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
35480 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35490 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69  t void*, int,voi
354a0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51  d(*)(void*));.SQ
354b0 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71  LITE_API void sq
354c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
354d0 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ue(sqlite3_conte
354e0 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c  xt*, sqlite3_val
354f0 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
35500 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
35510 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71  sult_zeroblob(sq
35520 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35530 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  int n);../*.** C
35540 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20  API3REF: Define 
35550 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65  New Collating Se
35560 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  quences.**.** ^T
35570 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
35580 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d  dd, remove, or m
35590 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69  odify a [collati
355a0 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a  on] associated.*
355b0 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  * with the [data
355c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
355d0 20 73 70 65 63 69 66 69 65 64 20 61 73 20 74 68   specified as th
355e0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
355f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
35600 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69  e of the collati
35610 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  on is a UTF-8 st
35620 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69  ring.** for sqli
35630 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
35640 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  tion() and sqlit
35650 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
35660 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20  ion_v2().** and 
35670 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
35680 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  in native byte o
35690 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33  rder for sqlite3
356a0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
356b0 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61  n16()..** ^Colla
356c0 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20  tion names that 
356d0 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63  compare equal ac
356e0 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69  cording to [sqli
356f0 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20  te3_strnicmp()] 
35700 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65  are.** considere
35710 64 20 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65  d to be the same
35720 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   name..**.** ^(T
35730 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
35740 74 20 28 65 54 65 78 74 52 65 70 29 20 6d 75 73  t (eTextRep) mus
35750 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20  t be one of the 
35760 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75  constants:.** <u
35770 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
35780 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69  TE_UTF8],.** <li
35790 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c  > [SQLITE_UTF16L
357a0 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  E],.** <li> [SQL
357b0 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
357c0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
357d0 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  F16], or.** <li>
357e0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
357f0 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c  LIGNED]..** </ul
35800 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78  >)^.** ^The eTex
35810 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65  tRep argument de
35820 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63  termines the enc
35830 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73  oding of strings
35840 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68   passed.** to th
35850 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
35860 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78  tion callback, x
35870 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68  Callback..** ^Th
35880 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d  e [SQLITE_UTF16]
35890 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46   and [SQLITE_UTF
358a0 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75  16_ALIGNED] valu
358b0 65 73 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a  es for eTextRep.
358c0 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73  ** force strings
358d0 20 74 6f 20 62 65 20 55 54 46 31 36 20 77 69 74   to be UTF16 wit
358e0 68 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  h native byte or
358f0 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  der..** ^The [SQ
35900 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
35910 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54  ED] value for eT
35920 65 78 74 52 65 70 20 66 6f 72 63 65 73 20 73 74  extRep forces st
35930 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a  rings to begin.*
35940 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74  * on an even byt
35950 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a  e address..**.**
35960 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61 72 67   ^The fourth arg
35970 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20  ument, pArg, is 
35980 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  an application d
35990 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ata pointer that
359a0 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68   is passed.** th
359b0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
359c0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
359d0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
359e0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a  ction callback..
359f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68  **.** ^The fifth
35a00 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c   argument, xCall
35a10 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74  back, is a point
35a20 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  er to the collat
35a30 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ing function..**
35a40 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61   ^Multiple colla
35a50 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63  ting functions c
35a60 61 6e 20 62 65 20 72 65 67 69 73 74 65 72 65 64  an be registered
35a70 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
35a80 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68  name but.** with
35a90 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
35aa0 52 65 70 20 70 61 72 61 6d 65 74 65 72 73 20 61  Rep parameters a
35ab0 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  nd SQLite will u
35ac0 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20  se whichever.** 
35ad0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
35ae0 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
35af0 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73  nt of data trans
35b00 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49  formation..** ^I
35b10 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20  f the xCallback 
35b20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c  argument is NULL
35b30 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74   then the collat
35b40 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a  ing function is.
35b50 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68  ** deleted.  ^Wh
35b60 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67  en all collating
35b70 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e   functions havin
35b80 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  g the same name 
35b90 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20  are deleted,.** 
35ba0 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69  that collation i
35bb0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62  s no longer usab
35bc0 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  le..**.** ^The c
35bd0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
35be0 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  n callback is in
35bf0 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70  voked with a cop
35c00 79 20 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a  y of the pArg .*
35c10 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  * application da
35c20 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77  ta pointer and w
35c30 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20  ith two strings 
35c40 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  in the encoding 
35c50 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
35c60 74 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67  the eTextRep arg
35c70 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c  ument.  The coll
35c80 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
35c90 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a  ust return an.**
35ca0 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
35cb0 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c   negative, zero,
35cc0 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20   or positive.** 
35cd0 69 66 20 74 68 65 20 66 69 72 73 74 20 73 74 72  if the first str
35ce0 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ing is less than
35cf0 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67  , equal to, or g
35d00 72 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20  reater than the 
35d10 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65  second,.** respe
35d20 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c  ctively.  A coll
35d30 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d  ating function m
35d40 75 73 74 20 61 6c 77 61 79 73 20 72 65 74 75 72  ust always retur
35d50 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65  n the same answe
35d60 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73  r.** given the s
35d70 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20  ame inputs.  If 
35d80 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c  two or more coll
35d90 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20  ating functions 
35da0 61 72 65 20 72 65 67 69 73 74 65 72 65 64 0a 2a  are registered.*
35db0 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20 63 6f  * to the same co
35dc0 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73  llation name (us
35dd0 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20 65 54  ing different eT
35de0 65 78 74 52 65 70 20 76 61 6c 75 65 73 29 20 74  extRep values) t
35df0 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20  hen all.** must 
35e00 67 69 76 65 20 61 6e 20 65 71 75 69 76 61 6c 65  give an equivale
35e10 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e 20 69  nt answer when i
35e20 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71 75 69  nvoked with equi
35e30 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a  valent strings..
35e40 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67  ** The collating
35e50 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f   function must o
35e60 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  bey the followin
35e70 67 20 70 72 6f 70 65 72 74 69 65 73 20 66 6f 72  g properties for
35e80 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20   all.** strings 
35e90 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a  A, B, and C:.**.
35ea0 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ol>.** <li> 
35eb0 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d  If A==B then B==
35ec0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d  A..** <li> If A=
35ed0 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e  =B and B==C then
35ee0 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   A==C..** <li> I
35ef0 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20 42 26  f A&lt;B THEN B&
35f00 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  gt;A..** <li> If
35f10 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74   A&lt;B and B&lt
35f20 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a  ;C then A&lt;C..
35f30 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ol>.**.** I
35f40 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  f a collating fu
35f50 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79  nction fails any
35f60 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20 63 6f   of the above co
35f70 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20 74 68  nstraints and th
35f80 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20  at.** collating 
35f90 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72 65 67  function is  reg
35fa0 69 73 74 65 72 65 64 20 61 6e 64 20 75 73 65 64  istered and used
35fb0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
35fc0 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ior of SQLite.**
35fd0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
35fe0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35ff0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36000 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20 6c 69  on_v2() works li
36010 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ke sqlite3_creat
36020 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a  e_collation().**
36030 20 77 69 74 68 20 74 68 65 20 61 64 64 69 74 69   with the additi
36040 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44 65 73  on that the xDes
36050 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73  troy callback is
36060 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67   invoked on pArg
36070 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c   when.** the col
36080 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
36090 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e  is deleted..** ^
360a0 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  Collating functi
360b0 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ons are deleted 
360c0 77 68 65 6e 20 74 68 65 79 20 61 72 65 20 6f 76  when they are ov
360d0 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61 74 65  erridden by late
360e0 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68  r.** calls to th
360f0 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61  e collation crea
36100 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f  tion functions o
36110 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64  r when the.** [d
36120 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36130 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20 75 73  on] is closed us
36140 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  ing [sqlite3_clo
36150 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  se()]..**.** ^Th
36160 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62  e xDestroy callb
36170 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75  ack is <u>not</u
36180 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68 65 20  > called if the 
36190 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61  .** sqlite3_crea
361a0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
361b0 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  ) function fails
361c0 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  .  Applications 
361d0 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  that invoke.** s
361e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
361f0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 69 74  llation_v2() wit
36200 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65  h a non-NULL xDe
36210 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74 20 73  stroy argument s
36220 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20  hould .** check 
36230 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20  the return code 
36240 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66 20 74  and dispose of t
36250 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
36260 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ata pointer.** t
36270 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68 65 72  hemselves rather
36280 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e 67 20   than expecting 
36290 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c 20 77  SQLite to deal w
362a0 69 74 68 20 69 74 20 66 6f 72 20 74 68 65 6d 2e  ith it for them.
362b0 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69 66 66  .** This is diff
362c0 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65 72 79  erent from every
362d0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
362e0 74 65 72 66 61 63 65 2e 20 20 54 68 65 20 69 6e  terface.  The in
362f0 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20  consistency .** 
36300 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65 20 62  is unfortunate b
36310 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61  ut cannot be cha
36320 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  nged without bre
36330 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64 73 20  aking backwards 
36340 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  .** compatibilit
36350 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  y..**.** See als
36360 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  o:  [sqlite3_col
36370 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d  lation_needed()]
36380 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f   and [sqlite3_co
36390 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
363a0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
363b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
363c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
363d0 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
363e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
363f0 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
36400 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
36410 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
36420 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
36430 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
36440 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51  nst void*).);.SQ
36450 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
36460 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36470 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ation_v2(.  sqli
36480 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
36490 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
364a0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
364b0 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
364c0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
364d0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
364e0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
364f0 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  d*),.  void(*xDe
36500 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
36510 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
36520 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36530 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73 71  ollation16(.  sq
36540 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74  lite3*, .  const
36550 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20   void *zName,.  
36560 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
36570 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
36580 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
36590 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
365a0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
365b0 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
365c0 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74 69  API3REF: Collati
365d0 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62 61  on Needed Callba
365e0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76  cks.**.** ^To av
365f0 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72 65  oid having to re
36600 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c 61  gister all colla
36610 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20 62  tion sequences b
36620 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73 65  efore a database
36630 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 2c  .** can be used,
36640 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62 61   a single callba
36650 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  ck function may 
36660 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77 69  be registered wi
36670 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  th the.** [datab
36680 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36690 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
366a0 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66 69  enever an undefi
366b0 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a  ned collation.**
366c0 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65 71   sequence is req
366d0 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uired..**.** ^If
366e0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
366f0 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69 6e   registered usin
36700 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  g the sqlite3_co
36710 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
36720 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69 74   API,.** then it
36730 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20 6e   is passed the n
36740 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e 65  ames of undefine
36750 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  d collation sequ
36760 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67 73  ences as strings
36770 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20 55  .** encoded in U
36780 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74 65  TF-8. ^If sqlite
36790 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
367a0 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c 0a  ed16() is used,.
367b0 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72 65  ** the names are
367c0 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d 31   passed as UTF-1
367d0 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61 74  6 in machine nat
367e0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
367f0 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65 69  ** ^A call to ei
36800 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72 65  ther function re
36810 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73 74  places the exist
36820 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65  ing collation-ne
36830 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a  eded callback..*
36840 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65 20  *.** ^(When the 
36850 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
36860 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20 61  ked, the first a
36870 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 69  rgument passed i
36880 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20 74  s a copy.** of t
36890 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
368a0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  nt to sqlite3_co
368b0 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 29  llation_needed()
368c0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
368d0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31  ollation_needed1
368e0 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  6().  The second
368f0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
36900 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
36910 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74 68  nection.  The th
36920 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
36930 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 55  one of [SQLITE_U
36940 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55 54  TF8], [SQLITE_UT
36950 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  F16BE],.** or [S
36960 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c 20  QLITE_UTF16LE], 
36970 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20 6d  indicating the m
36980 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66 6f  ost desirable fo
36990 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74  rm of the collat
369a0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
369b0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
369c0 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70  d.  The fourth p
369d0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
369e0 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 72  name of the.** r
369f0 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  equired collatio
36a00 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a  n sequence.)^.**
36a10 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b  .** The callback
36a20 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
36a30 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64 65   register the de
36a40 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20  sired collation 
36a50 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
36a60 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36a70 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
36a80 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36a90 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  16()], or.** [sq
36aa0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36ab0 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f  lation_v2()]..*/
36ac0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
36ad0 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
36ae0 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c 69  n_needed(.  sqli
36af0 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 20  te3*, .  void*, 
36b00 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  .  void(*)(void*
36b10 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54  ,sqlite3*,int eT
36b20 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68 61  extRep,const cha
36b30 72 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  r*).);.SQLITE_AP
36b40 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
36b50 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
36b60 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
36b70 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
36b80 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
36b90 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
36ba0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23  nst void*).);..#
36bb0 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53  ifdef SQLITE_HAS
36bc0 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65  _CODEC./*.** Spe
36bd0 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
36be0 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
36bf0 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
36c00 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
36c10 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
36c20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
36c30 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
36c40 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
36c50 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
36c60 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
36c70 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
36c80 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
36c90 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
36ca0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
36cb0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
36cc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36cd0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
36ce0 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
36cf0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
36d00 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
36d10 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 53   The key */.);.S
36d20 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
36d30 6c 69 74 65 33 5f 6b 65 79 5f 76 32 28 0a 20 20  lite3_key_v2(.  
36d40 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
36d50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
36d60 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
36d70 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
36d80 6e 73 74 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d  nst char *zDbNam
36d90 65 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  e,           /* 
36da0 4e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  Name of the data
36db0 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  base */.  const 
36dc0 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
36dd0 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
36de0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
36df0 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
36e00 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
36e10 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
36e20 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
36e30 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
36e40 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
36e50 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
36e60 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
36e70 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
36e80 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
36e90 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
36ea0 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
36eb0 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
36ec0 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
36ed0 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
36ee0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
36ef0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
36f00 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79  nt sqlite3_rekey
36f10 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
36f20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36f30 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74     /* Database t
36f40 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a  o be rekeyed */.
36f50 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
36f60 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
36f70 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
36f80 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
36f90 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b   int sqlite3_rek
36fa0 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  ey_v2(.  sqlite3
36fb0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
36fc0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
36fd0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
36fe0 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  d */.  const cha
36ff0 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20  r *zDbName,     
37000 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
37010 20 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f   the database */
37020 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70  .  const void *p
37030 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20  Key, int nKey   
37040 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79    /* The new key
37050 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70   */.);../*.** Sp
37060 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61  ecify the activa
37070 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53  tion key for a S
37080 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  EE database.  Un
37090 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
370a0 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
370b0 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  SEE routines wil
370c0 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54  l work..*/.SQLIT
370d0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
370e0 65 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28  e3_activate_see(
370f0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
37100 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20  PassPhrase      
37110 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20    /* Activation 
37120 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e  phrase */.);.#en
37130 64 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  dif..#ifdef SQLI
37140 54 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a  TE_ENABLE_CEROD.
37150 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68  /*.** Specify th
37160 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79  e activation key
37170 20 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74   for a CEROD dat
37180 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
37190 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
371a0 6e 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20  ne of the CEROD 
371b0 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f  routines will wo
371c0 72 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  rk..*/.SQLITE_AP
371d0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61  I void sqlite3_a
371e0 63 74 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20  ctivate_cerod(. 
371f0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
37200 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
37210 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
37220 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
37230 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
37240 46 3a 20 53 75 73 70 65 6e 64 20 45 78 65 63 75  F: Suspend Execu
37250 74 69 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74  tion For A Short
37260 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20   Time.**.** The 
37270 73 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20  sqlite3_sleep() 
37280 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
37290 74 68 65 20 63 75 72 72 65 6e 74 20 74 68 72 65  the current thre
372a0 61 64 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78  ad to suspend ex
372b0 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61  ecution.** for a
372c0 74 20 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72  t least a number
372d0 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
372e0 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 69 74   specified in it
372f0 73 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  s parameter..**.
37300 2a 2a 20 49 66 20 74 68 65 20 6f 70 65 72 61 74  ** If the operat
37310 69 6e 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20  ing system does 
37320 6e 6f 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65  not support slee
37330 70 20 72 65 71 75 65 73 74 73 20 77 69 74 68 0a  p requests with.
37340 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74  ** millisecond t
37350 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20  ime resolution, 
37360 74 68 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69  then the time wi
37370 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70  ll be rounded up
37380 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65   to.** the neare
37390 73 74 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e  st second. The n
373a0 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65  umber of millise
373b0 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61  conds of sleep a
373c0 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65  ctually.** reque
373d0 73 74 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70  sted from the op
373e0 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69  erating system i
373f0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
37400 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d  * ^SQLite implem
37410 65 6e 74 73 20 74 68 69 73 20 69 6e 74 65 72 66  ents this interf
37420 61 63 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74  ace by calling t
37430 68 65 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d  he xSleep().** m
37440 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66  ethod of the def
37450 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
37460 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74  s] object.  If t
37470 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68  he xSleep() meth
37480 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66  od.** of the def
37490 61 75 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20  ault VFS is not 
374a0 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72  implemented corr
374b0 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d  ectly, or not im
374c0 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20  plemented at.** 
374d0 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65  all, then the be
374e0 68 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65  havior of sqlite
374f0 33 5f 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65  3_sleep() may de
37500 76 69 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64  viate from the d
37510 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e  escription.** in
37520 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
37530 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a 53 51 4c  ragraphs..*/.SQL
37540 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
37550 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
37560 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37570 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
37580 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
37590 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
375a0 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
375b0 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
375c0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
375d0 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
375e0 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
375f0 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
37600 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
37610 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
37620 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
37630 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
37640 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
37650 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
37660 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
37670 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
37680 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49  directory.)^  ^I
37690 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
376a0 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
376b0 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
376c0 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
376d0 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
376e0 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
376f0 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
37700 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73 20  ry..**.** It is 
37710 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64  not safe to read
37720 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
37730 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72 65  variable in more
37740 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68 72   than one.** thr
37750 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20 20  ead at a time.  
37760 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
37770 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
37780 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a   this variable.*
37790 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73 65  * if a [database
377a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
377b0 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74 68  being used at th
377c0 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20 61  e same time in a
377d0 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68 72   separate.** thr
377e0 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69 6e  ead..** It is in
377f0 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69 73  tended that this
37800 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65 74   variable be set
37810 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72 74   once.** as part
37820 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69 74   of process init
37830 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 62  ialization and b
37840 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74 65  efore any SQLite
37850 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 6f   interface.** ro
37860 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65 6e  utines have been
37870 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61 74   called and that
37880 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 72   this variable r
37890 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64 0a  emain unchanged.
378a0 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a 2a  ** thereafter..*
378b0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65 6d 70 5f  *.** ^The [temp_
378c0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
378d0 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64 69  pragma] may modi
378e0 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
378f0 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69 74   and cause.** it
37900 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
37910 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
37920 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
37930 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f 72  c].  ^Furthermor
37940 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65 6d 70 5f  e,.** the [temp_
37950 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37960 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20 61  pragma] always a
37970 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79 20  ssumes that any 
37980 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20 74  string.** that t
37990 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f 69  his variable poi
379a0 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20 69  nts to is held i
379b0 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  n memory obtaine
379c0 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
379d0 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64 20  te3_malloc] and 
379e0 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20 61  the pragma may a
379f0 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20 74  ttempt to free t
37a00 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75 73  hat memory.** us
37a10 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  ing [sqlite3_fre
37a20 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69 66  e]..** Hence, if
37a30 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
37a40 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65 63  s modified direc
37a50 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20 73  tly, either it s
37a60 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64 65  hould be.** made
37a70 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74 6f   NULL or made to
37a80 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72 79   point to memory
37a90 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
37aa0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 0a  sqlite3_malloc].
37ab0 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20 75  ** or else the u
37ac0 73 65 20 6f 66 20 74 68 65 20 5b 74 65 6d 70 5f  se of the [temp_
37ad0 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
37ae0 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20 62  pragma] should b
37af0 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a 0a 2a 2a  e avoided..**.**
37b00 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
37b10 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
37b20 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
37b30 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
37b40 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
37b50 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
37b60 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5d 20 6f  [sqlite3_open] o
37b70 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  r [sqlite3_open_
37b80 76 32 5d 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  v2].  Otherwise,
37b90 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
37ba0 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
37bb0 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
37bc0 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
37bd0 20 66 61 69 6c 2e 20 20 48 65 72 65 20 69 73 20   fail.  Here is 
37be0 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65 20 6f 66  an.** example of
37bf0 20 68 6f 77 20 74 6f 20 64 6f 20 74 68 69 73 20   how to do this 
37c00 75 73 69 6e 67 20 43 2b 2b 20 77 69 74 68 20 74  using C++ with t
37c10 68 65 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69  he Windows Runti
37c20 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  me:.**.** <block
37c30 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 4c  quote><pre>.** L
37c40 50 43 57 53 54 52 20 7a 50 61 74 68 20 3d 20 57  PCWSTR zPath = W
37c50 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61 67 65 3a  indows::Storage:
37c60 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44 61 74 61  :ApplicationData
37c70 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a 2a 20 26  ::Current->.** &
37c80 6e 62 73 70 3b 20 20 20 20 20 54 65 6d 70 6f 72  nbsp;     Tempor
37c90 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61 74 68 2d  aryFolder->Path-
37ca0 3e 44 61 74 61 28 29 3b 0a 2a 2a 20 63 68 61 72  >Data();.** char
37cb0 20 7a 50 61 74 68 42 75 66 26 23 39 31 3b 4d 41   zPathBuf&#91;MA
37cc0 58 5f 50 41 54 48 20 2b 20 31 26 23 39 33 3b 3b  X_PATH + 1&#93;;
37cd0 0a 2a 2a 20 6d 65 6d 73 65 74 28 7a 50 61 74 68  .** memset(zPath
37ce0 42 75 66 2c 20 30 2c 20 73 69 7a 65 6f 66 28 7a  Buf, 0, sizeof(z
37cf0 50 61 74 68 42 75 66 29 29 3b 0a 2a 2a 20 57 69  PathBuf));.** Wi
37d00 64 65 43 68 61 72 54 6f 4d 75 6c 74 69 42 79 74  deCharToMultiByt
37d10 65 28 43 50 5f 55 54 46 38 2c 20 30 2c 20 7a 50  e(CP_UTF8, 0, zP
37d20 61 74 68 2c 20 2d 31 2c 20 7a 50 61 74 68 42 75  ath, -1, zPathBu
37d30 66 2c 20 73 69 7a 65 6f 66 28 7a 50 61 74 68 42  f, sizeof(zPathB
37d40 75 66 29 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  uf),.** &nbsp;  
37d50 20 20 20 4e 55 4c 4c 2c 20 4e 55 4c 4c 29 3b 0a     NULL, NULL);.
37d60 2a 2a 20 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  ** sqlite3_temp_
37d70 64 69 72 65 63 74 6f 72 79 20 3d 20 73 71 6c 69  directory = sqli
37d80 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 25 73 22  te3_mprintf("%s"
37d90 2c 20 7a 50 61 74 68 42 75 66 29 3b 0a 2a 2a 20  , zPathBuf);.** 
37da0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
37db0 74 65 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te>.*/.SQLITE_AP
37dc0 49 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  I SQLITE_EXTERN 
37dd0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65  char *sqlite3_te
37de0 6d 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f  mp_directory;../
37df0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
37e00 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
37e10 72 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61  r Holding Databa
37e20 73 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e  se Files.**.** ^
37e30 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20  (If this global 
37e40 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65  variable is made
37e50 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73   to point to a s
37e60 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a  tring which is.*
37e70 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20  * the name of a 
37e80 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64  folder (a.k.a. d
37e90 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20  irectory), then 
37ea0 61 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c  all database fil
37eb0 65 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20  es.** specified 
37ec0 77 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20  with a relative 
37ed0 70 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65  pathname and cre
37ee0 61 74 65 64 20 6f 72 20 61 63 63 65 73 73 65 64  ated or accessed
37ef0 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68   by.** SQLite wh
37f00 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74  en using a built
37f10 2d 69 6e 20 77 69 6e 64 6f 77 73 20 5b 73 71 6c  -in windows [sql
37f20 69 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 20  ite3_vfs | VFS] 
37f30 77 69 6c 6c 20 62 65 20 61 73 73 75 6d 65 64 0a  will be assumed.
37f40 2a 2a 20 74 6f 20 62 65 20 72 65 6c 61 74 69 76  ** to be relativ
37f50 65 20 74 6f 20 74 68 61 74 20 64 69 72 65 63 74  e to that direct
37f60 6f 72 79 2e 29 5e 20 5e 49 66 20 74 68 69 73 20  ory.)^ ^If this 
37f70 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55  variable is a NU
37f80 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2c 20 74  LL.** pointer, t
37f90 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
37fa0 65 73 20 74 68 61 74 20 61 6c 6c 20 64 61 74 61  es that all data
37fb0 62 61 73 65 20 66 69 6c 65 73 20 73 70 65 63 69  base files speci
37fc0 66 69 65 64 0a 2a 2a 20 77 69 74 68 20 61 20 72  fied.** with a r
37fd0 65 6c 61 74 69 76 65 20 70 61 74 68 6e 61 6d 65  elative pathname
37fe0 20 61 72 65 20 72 65 6c 61 74 69 76 65 20 74 6f   are relative to
37ff0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69 72   the current dir
38000 65 63 74 6f 72 79 0a 2a 2a 20 66 6f 72 20 74 68  ectory.** for th
38010 65 20 70 72 6f 63 65 73 73 2e 20 20 4f 6e 6c 79  e process.  Only
38020 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53   the windows VFS
38030 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20 74 68   makes use of th
38040 69 73 20 67 6c 6f 62 61 6c 0a 2a 2a 20 76 61 72  is global.** var
38050 69 61 62 6c 65 3b 20 69 74 20 69 73 20 69 67 6e  iable; it is ign
38060 6f 72 65 64 20 62 79 20 74 68 65 20 75 6e 69 78  ored by the unix
38070 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e   VFS..**.** Chan
38080 67 69 6e 67 20 74 68 65 20 76 61 6c 75 65 20 6f  ging the value o
38090 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
380a0 77 68 69 6c 65 20 61 20 64 61 74 61 62 61 73 65  while a database
380b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 0a 2a   connection is.*
380c0 2a 20 6f 70 65 6e 20 63 61 6e 20 72 65 73 75 6c  * open can resul
380d0 74 20 69 6e 20 61 20 63 6f 72 72 75 70 74 20 64  t in a corrupt d
380e0 61 74 61 62 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49  atabase..**.** I
380f0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
38100 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20   read or modify 
38110 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e  this variable in
38120 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a   more than one.*
38130 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69  * thread at a ti
38140 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73  me.  It is not s
38150 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d  afe to read or m
38160 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
38170 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74  ble.** if a [dat
38180 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
38190 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20  ] is being used 
381a0 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
381b0 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a   in a separate.*
381c0 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20  * thread..** It 
381d0 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74  is intended that
381e0 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62   this variable b
381f0 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73  e set once.** as
38200 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73   part of process
38210 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
38220 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53  and before any S
38230 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a  QLite interface.
38240 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65  ** routines have
38250 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64   been called and
38260 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61   that this varia
38270 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61  ble remain uncha
38280 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74  nged.** thereaft
38290 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  er..**.** ^The [
382a0 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
382b0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79  tory pragma] may
382c0 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72   modify this var
382d0 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a  iable and cause.
382e0 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74  ** it to point t
382f0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
38300 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
38310 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68  malloc].  ^Furth
38320 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b  ermore,.** the [
38330 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
38340 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77  tory pragma] alw
38350 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74  ays assumes that
38360 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74   any string.** t
38370 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
38380 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68  e points to is h
38390 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62  eld in memory ob
383a0 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
383b0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
383c0 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20   and the pragma 
383d0 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66  may attempt to f
383e0 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a  ree that memory.
383f0 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ** using [sqlite
38400 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63  3_free]..** Henc
38410 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61  e, if this varia
38420 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20  ble is modified 
38430 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72  directly, either
38440 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a   it should be.**
38450 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61   made NULL or ma
38460 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d  de to point to m
38470 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
38480 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
38490 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20  loc].** or else 
384a0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  the use of the [
384b0 64 61 74 61 5f 73 74 6f 72 65 5f 64 69 72 65 63  data_store_direc
384c0 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f  tory pragma] sho
384d0 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a  uld be avoided..
384e0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  */.SQLITE_API SQ
384f0 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61 72  LITE_EXTERN char
38500 20 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 64   *sqlite3_data_d
38510 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a 2a  irectory;../*.**
38520 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74 20   CAPI3REF: Test 
38530 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74 20  For Auto-Commit 
38540 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  Mode.** KEYWORDS
38550 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f  : {autocommit mo
38560 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  de}.**.** ^The s
38570 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f 63  qlite3_get_autoc
38580 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61 63  ommit() interfac
38590 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  e returns non-ze
385a0 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69 66  ro or.** zero if
385b0 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61 62   the given datab
385c0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
385d0 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20 61  s or is not in a
385e0 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c 0a  utocommit mode,.
385f0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
38600 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f    ^Autocommit mo
38610 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66 61  de is on by defa
38620 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d  ult..** ^Autocom
38630 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73 61  mit mode is disa
38640 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49 4e  bled by a [BEGIN
38650 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
38660 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
38670 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20 62   is re-enabled b
38680 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72 20  y a [COMMIT] or 
38690 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a 2a  [ROLLBACK]..**.*
386a0 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69 6e  * If certain kin
386b0 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63 63  ds of errors occ
386c0 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65 6e  ur on a statemen
386d0 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74 69  t within a multi
386e0 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 72  -statement.** tr
386f0 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f 72  ansaction (error
38700 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51 4c  s including [SQL
38710 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c 49  ITE_FULL], [SQLI
38720 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b 53  TE_IOERR],.** [S
38730 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b 53  QLITE_NOMEM], [S
38740 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e 64  QLITE_BUSY], and
38750 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55   [SQLITE_INTERRU
38760 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a 2a  PT]) then the.**
38770 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69 67   transaction mig
38780 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ht be rolled bac
38790 6b 20 61 75 74 6f 6d 61 74 69